Here are lessons I learned the hard way so you don’t have to.


For a book title that has a sub title, use a colon to separate the title from the subtitle. For example in this book, it includes a subtitle and it is separated by a colon. I tried a hyphen first and that didn’t work. Colon is the right separator for AsciiDoctor.

= AsciiDoc Authoring: How To Make Books For Free (1)
  1. Note the ':' colon character as the separator.

One Sentence Per Line

Dan Allen recommended this and I think it has worked really well for me. It really shines when you use version control app to show the differences between versions over time.

The asciidoctor app puts all the sentences back into paragraphs for the published or rendered versions.

Image Borders

To automatically add a border around an image, add the following around it.

[.thumb] (1)
.The Sony Similar to What I Use (2)
image::media\DigitalRecorder.png[] (3)
  1. This AsciiDoctor code adds the border around the image.

  2. This is the figure title.

  3. This is the image path and filename reference.


Add the following attribute to the book file as follows.

= AsciiDoc Authoring: How To Make Books For Free
:author: Kevin Lanham
:icons: font (1)
  1. The icons attribute with the word font to the right turns on the fonts for callouts and admonitions. Do not leave a blank line between the attributes and the title.

Comments for intellectual property notes

Use comments for IP notes.

For example, for an image I got from a open licensing source, I can include the license type and the URL in a comment.

Comments for AsciiDoc are two forward slashes //.

Here is an example for attribution of an image.

.My Sample Image
// Pending permission from Disney. Request sent on 2016-07-15.

This keeps the IP to dos in proximity to the usage. When I get permission then I use a footnote to provide attribution rather than break the content.

Comments for Work to Be Done Later

I sometimes use comments to remind myself of the idea at a high level using comments. For example, consider this example source text in AsciiDoc.

Here is a paragraph, blah blah blah.

// Add a summary of the Huckleberry Finn story

Here is another paragraph, yada yada yada.

The nice thing about comments is that they don’t render to the reader’s version. They’re just for the creators.


Line By Line

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

Back to Overview