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:
- css: this folder contains the master.styl file, which is your main option for styling the textbook beyond the defaults it ships with. It is written in Stylus, but you can replace it with a plain master.css file.
- js: this folder contains the main.coffee file, which is your main option for changing the javascript behaviour of the entire textbook. It is written in CoffeeScript, but you can replace it with a plain main.js file.
- img: use this folder to store your images and photos
- text: this folder contains the actual pages and text content of the textbook
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:
- Introduction
- Properties of metals and non-metals
- Physical properties
- Metals
- Non-metals
- Chemical properties
- Metals
- Non-metals
- Noble metals
- Corrosion of metals
- Prevention of corrosion
- Alloys
- Assessment
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)