The first time you try anything new, it can seem hard or even intimidating. The first time you try AsciiDoc is no different. AsciiDoc is easy to use, so let’s walk through it step-by-step.

If you have never used the terminal or command line, see [CommandLine] before starting this chapter.

Work Area

First, let’s set up a working area on our computer. You only need to do this setup once per book project.

I called my folder AsciiDoc_Book because it is for this book. Name your folder a name that you’ll recognize for your own book.

Figure 1. Make an Empty Folder

Next, let’s set up the work area with some folders to organize things.

On a Mac, you can left click and select New Folder or use the terminal to make new folders.

Make a folder for the following:

  • Media (images, video, audio files)

  • Chapters and Sections (or you can call this topics)

  • eBook

  • PrintPDF

  • Optionally, add a folder for glossary terms if you plan to include a big glossary and would like to reuse terms.

Figure 2. Initial Folder Setup
Don’t use spaces in file and folder names. It causes problems with rendering later.

Next let’s make two empty plain text files. The first we’ll need is the book file itself. On Windows, right click and select new, then text file, then rename it to your book’s name MakeBooksFree.adoc. On a Mac, we use the command line and type touch MakeBooksFree.adoc.

No one will see this title, so make it up quickly and go. You can change your title that the public sees later.
touch MakeBooksFree.adoc (1)
  1. The command touch on a Mac is how you create a new file from the terminal.

The command touch on a Mac is how you create a new file from the terminal.

Figure 3. Add Empty Book File
I’m using a modular approach, so the book file will not contain all your content, but is more like a map to the content files so the application knows how to render it. This associates to the lego instructions analogy I was using earlier.

Next, let’s aim for a quick success by making a simple book to test that it works before we spend too much effort writing.

Let’s set up a chapter with fake text, sometimes called lorem ipsum text just so you can see the book easily render in HTML and get a sense of how real text might be laid out. Fake text is not supposed to mean anything, but is simply intended to show where the content will be after it’s written.

Open the terminal or command line and change directories to the Chapters_and_Sections folder.

cd Chapters_and_Sections
Figure 4. Change Directory

In the terminal, make a new empty file for the example content.

touch example1.adoc (1)
  1. The command touch on a Mac is how you create a new file from the terminal.

Figure 5. Creating the File for the Example Chapter With the Terminal

Write Your First Chapter

This section assumes you have already installed the Atom text editor. See [installAtom].

Open this example1.adoc file using the Atom text editor, or your favorite text editor.

Add the chapter title as in the following example.

== Example Title for Basic Text Chapter (1)
  1. The two equal signs tell the rendering app that this is a chapter title.

Now let’s add some fake text. You can use blah blah blah or use lorem ipsum fake text.

With Atom, you can wrap any text that goes off the screen using the menus View | Toggle Soft Wrap.

Now your file should look something like the following screenshot. I have spell check in Atom that shows the squiggly lines under all the text spelling not recognized.

Figure 6. My Example Chapter with Lorem Ipsum Fake Text

Okay, now that we have a chapter with some content—​a lego block so to speak—​we need the map to tell the book to include this chapter.

Next let’s edit the lego instructions, or the book map file. AsciiDoc does not really call it that, but I like the image that the term map evokes.

Change back to the main working directory.

cd ..

Open the main book file in Atom or your text editor, my book file is called MakeBooksFree.adoc. Type in a simple book.

= Make Books for Free (2)
:author: Kevin Lanham (3)

include::Chapters_and_Sections/example1.adoc[] (4)
  1. Add a blank line at the top of each *.adoc file to prevent AsciiDoctor from having errors when adding different files back together again. The blanks do not show up in the published version, but only in the source files.

  2. This is the book title that the readers will see. The single equal sign indicates the book title. Notice the space between the equal sign and the title.

  3. The :author: attribute tells the rendering app that the next things are my first and last name.

  4. Rather than typing all our book content into this book file directly—​which you can do if you prefer that—​I’m showing a modular approach where I link to the chapters. So this book file is more analogous to the lego instructions to tell the rendering app where to put all the contents for my book.

Don’t actually type the numbers (1), (2), (3), (4) at the end of each line in the preceding example. Those are for me to reference each line as I explain it to you in writting, since I’m not physically present with you to point my finger at the appropriate line.

Simple and easy. We’re done "writing" a book with one chapter using AsciiDoc plain text format.

Let’s now render it to HTML5 and view it in an internet browser.

If you move the files to a different location, you have to update the include statements in the book file (i.e. in MakeBooksFree.adoc) to show the new path to the AsciiDoc file. Otherwise you’ll break your book.
I forgot where I read this, but add a blank line at the top of each *.adoc file before the title line so that the AsciiDoctor rendering app does not choke. I’ve only had a problem once in 1.5 years of using AsciiDoc. I had forgotten to add the blank line and got an error. Adding the blank line for the chapters and sections fixed the error.

Line By Line

Here a Little, There a Little, Layer by Layer.

Back to Overview