Learn Forward Author

Installation

Install node.js, and then run sudo npm install -g lfa.

Usage

LFA is a command line utility. To use it, simply run lfa in your terminal, which should greet you with the basic help and tell you what commands are available.

To start a new project, run lfa new followed by your project's name. For example:

~ $ lfa new cats
new project created at /cats

Then, navigate into your project folder:

~ $ cd cats
~/cats $ ls
config.jade
css
img
js
text

To compile and view your project, run lfa watch, which will open a new tab in your default browser.

Project structure

By default, a blank textbook starts out with four folders and one file. The config.jade file is used to define things like the title of your textbook that will appear in the browser tab. By default, this is "My new textbook", and you should change it when you start a new project.

As for the folders, they're rather self-explanatory:

In addition to these, you can add folders with any name and content of your choosing (i.e. widgets, audio) and they will be automatically copied over as-is during the build phase of your project.

Editing the content

After running lfa watch, a browser tab should open with the first page of your textbook. To edit it, open text/ch01/00.jade in your favourite code editor.

Pages are written in .jade, which is a language that compiles to plain HTML. If you are not familiar with .jade, you should peruse the basic tutorial to get an idea, but don't sweat it if things aren't completely clear by the end of it.

Let's take a look at the source code of the first page of our textbook:

---
title: Chapter 1
---

h1= title

p Looks like everything is working! You can edit...

p Lorem ipsum dolor sit amet...

Pages are comprised of two sections: frontmatter, and the content.

The frontmatter section is used to declare the title key, which is used to generate the table of contents. Go ahead and change it to something else, and save the file. The project should automatically recompile, and the table of contents will update. To declare additional keys, which can be anything you want or have specific meaning, simply add another key: value pair before the closing --- line.

Everything after the closing --- line is pure jade content. This is where you declare your headings, paragraphs, images, and widgets. You can go ahead and delete the boilerplate lorem ipsum paragraphs and headings in your files and start adding your own content.

LFA comes bundled with a bunch of useful patterns (WIP) that you can use to build your textbook, but you are free to delete the contents of the css/master.styl file and start from scratch.

Transferring your content from other sources (such as INDD)

The first thing you'll want to do is have all the static assets exported; images, videos, etc. Images should be preferably in either jpg or png format, exported with the "save for web" option and of a reasonable size, but its up to you to decide what level of quality you need for your assets. We recommend exporting videos to appropriate cloud hosting platforms such as Vimeo and Youtube and embedding them.

Importing text content involves transferring it into preferred editor (we recommend Sublime Text 3 or TextMate 2) and adding in the necessary styling through patterns. You will also have to escape special characters should they not copy over correctly, or change the font to one that can display them in a desirable manner.

Organizing files and the table of contents (WIP)

Let's take a look at the contents of the text/ folder. You'll notice that files are structured in a certain manner.

text
├── ch01
│   ├── 00.jade
│   ├── 01.jade
│   └── 02.jade
├── ch02.jade
└── index.jade

The index.jade file is configured by default to redirect you to the first page of your textbook. If you would prefer to have the homepage of your textbook something else, such as a cover photo of the textbook or a message, you can remove the +redirect_home() line in the index.jade and add whatever content you wish. The index page is also hidden from the TOC by default, which is accomplishable by adding the hidden_toc: true pair in the frontmatter section of any page.

Moving on, the rest of the pages are structured into folders. These have to follow certain conventions. To illustrate, say you have to build a chemistry textbook that should have the following TOC:

To do so, you could use the following file structure:

text
├── ch00-intro.jade
├── ch01-prop
│   ├── 00-prop.jade
│   ├── 01-phys
│   │   ├── 00-phys.jade
│   │   ├── 01-metals.jade
│   │   ├── 02-non-metals.jade
│   └── 02-chem
│       ├── 00-chem.jade
│       ├── 01-metals.jade
│       └── 02-non-metals.jade
├── ch02-noble.jade
├── ch03-corro
│   ├── 00-corro.jade
│   └── 01-prevention.jade
├── ch04-alloys.jade
└── ch05-assessment.jade

That's a bit of a doozy, isn't it? Let's try to clarify it a bit by walking you through the table of contents for the aforementioned chemistry textbook.

The first item is called "Introduction", and is supposed to show up before everything else in the table of contents. Since it does not have any subchapters, it can be created as just a standalone file. The only condition necessary for it to show up before all your other pages in the table of contents is for its filename to list alphabetically before the other chapters.

You are allowed to name your files and folders however you wish, but keeping in mind that since they are going to be sorted alphabetically to decide their order in the table of contents, some conventions are necessary. The model that we personally encourage is to have main chapters all start with the chXX label in their names, followed by some short descriptive name that can help you identify at a glance which file has the information you need to edit.

That covers the first item. The second item, and the first chapter, is comprised of multiple subchapters. When you have a chapter that has two subchapters, you'll have to create a folder, and add three files inside: one for the chapter, and two (or as many as you need) for each subchapter. (TBC)