Tag: markdown

So I’m writing a book about Linux.

You’ll hear a lot more about this over the next few months, but one of the most interesting things I’ve discovered is Asciidoc, which is a fantastically thorough markup language for writing books. It’s like Markdown with even more options, like sidebars, notes, and tables. Asciidoc lets you just type, with very simple syntax controlling the formatting.

When I first started writing the book, I was using Word style sheets with LibreOffice. Manning, my publisher, offered .odt versions for OpenOffice, but I had trouble getting the styles to work. Ironically, I wound up using the Word .docx template, which worked best with LibreOffice. But the big problem was images—they just wouldn’t embed correctly. I was spending a decent chunk of time formatting when I needed to be writing.

Comments were also tough to parse. Jim Whitehurst actually got LibreOffice patched to better handle them while he was writing his book.

After a couple of chapters of fighting through the template, my editor suggested we switch to Asciidoc and my life instantly became easier.

With LibreOffice, I had to insert an image, number it, caption it, style it, and then hope that everything held together, while with Asciidoc, I just write something like this:

.Mint's Software Manager has a similar look to the Ubuntu Software Center.
image::../images/08_11.png[]

and Asciidoc handles everything else for me, even numbering the images in the captions.

This is what the above code renders as:

Asciidoc transformed into a PDF

A sidebar or note is as simple as something like this:

Asciidoc syntax for a note

which turns it into this:

Asciidoc syntax for a note rendered into a PDF

Asciidoc has formatting for heads and subheads and even automatically generates a table of contents based on them:

Asciidoc generates a table of contents automatically

You can write Asciidoc in anything since it’s just text, but I like to preview the code to make sure everything looks OK. There’s a gedit plugin but it seemed to require some work to get going and I was under the gun with deadlines, so I decided to use Atom, the GitHub-created text/code editor. It had a plugin that rendered Asciidoc. I wrote a few chapters with it, but the preview was sometimes peculiar. Notes and sidebars would expand into the whole document. Also, I couldn’t directly open Asciidoc formatted documents with it. Instead, I had to open Atom and then open a document via the Atom open menu.

Atom was fine, but annoying enough that I decided to try Brackets, the Adobe open-source code/text editor. It renders Asciidoc much better and while opening Asciidoc files still isn’t seamless, it’s better than Atom. I wish it had a running spellcheck instead of the ability to run a spellcheck when you’re done, but it previews what I need to see and gives me a running word count, so I’m pretty happy.

The Brackets text editor

Asciidoc rendered by Brackets

Brackets and Atom render in HTML but the a2x command (it’s part of the Asciidoc package) makes it very easy to convert the .adoc file to a PDF (although there’s some weird bug that causes the transformation to fail when image files have a period in the name). The output looks like a professionally formatted book chapter.

Asciidoc has been a life-saver for me. I’m lucky to be working with a publisher that uses it. I think it has applications for anyone who needs nice-looking PDFs or someone self-publishing. I also think it has tremendous implications for open education resources in that it allows someone to write a textbook without necessarily having to format it. You’d have a PDF ready very easily but you could still make the underlying Asciidoc available to people who wanted to modify the original work.

Markup languages like Asciidoc are fantastic for people like me who don’t want to deal with formatting. It’s saved me hours on the book (once we moved to Asciidoc, we were also able to use a private git repository to submit drafts back and forth; Asciidoc also has the ability to comment-out text which lets us share comments in the text) and allows me to focus on writing and not on styles and formatting. I’m not sure if Asciidoc has wide appeal for everyone, but if there’s a chance you can use it to move your work forward, I encourage you to spend some time with it.