AsciiDoc Writer’s Guide Table of Contents .................................................................................................................................. vii 1. Writing in AsciiDoc ................................................................................................ 1 1.1. “It’s just text, mate.” .................................................................................... 1 1.2. Content is king! ........................................................................................... 1 1.3. Admonitions ................................................................................................. 3 1.4. Mild punctuation, strong impact .................................................................. 3 1.4.1. Quoted text ....................................................................................... 3 1.4.2. Preventing substitution ...................................................................... 5 1.4.3. Replacements ................................................................................... 6 1.5. Lists, lists, lists ............................................................................................ 7 1.5.1. Lists of things .................................................................................... 7 1.5.2. Ordering the things ........................................................................... 9 1.5.3. Titling a list ...................................................................................... 11 1.5.4. Labeled lists .................................................................................... 11 1.5.5. Hybrid lists ...................................................................................... 13 1.5.6. Complex list content ....................................................................... 15 1.5.7. Dividing lists .................................................................................... 17 1.6. Links and images ...................................................................................... 17 1.6.1. External links ................................................................................... 17 1.6.2. Target window and role attributes for links ...................................... 18 1.6.3. Links to relative files ....................................................................... 19 1.6.4. Internal cross references ................................................................ 19 1.6.5. Images ............................................................................................ 19 1.7. Titles, titles, titles ....................................................................................... 21 1.7.1. Document title ................................................................................. 21 1.7.2. Document attributes ........................................................................ 23 1.7.3. Section titles .................................................................................... 24 1.7.4. Block titles ....................................................................................... 27 2. Building blocks in AsciiDoc ................................................................................. 28 2.1. Delimited blocks ........................................................................................ 28 2.2. Block metadata ......................................................................................... 30 2.3. Masquerading blocks ................................................................................ 31 2.3.1. Admonition blocks ........................................................................... 31 2.3.2. Listing and source code blocks ....................................................... 32 2.3.3. Open blocks .................................................................................... 33 2.3.4. Passthrough blocks ......................................................................... 34 ii AsciiDoc Writer’s Guide 2.4. Delimiters optional ..................................................................................... 34 2.5. A new perspective on tables ..................................................................... 35 3. What else can AsciiDoc do? ............................................................................... 40 4. Rendering your document ................................................................................... 41 4.1. Installing AsciiDoc ..................................................................................... 41 4.1.1. Installing AsciiDoc via a package manager .................................... 41 4.1.2. Installing AsciiDoc manually ........................................................... 42 4.2. Converting a document to HTML 5 ........................................................... 43 4.3. Converting a document to DocBook ......................................................... 46 4.4. Converting the document to PDF ............................................................. 47 4.5. Producing HTML-based presentations ...................................................... 47 4.6. Output galore ............................................................................................ 48 4.7. Where else is AsciiDoc rendered? ............................................................ 48 5. Wrap-up ............................................................................................................... 49 Glossary ................................................................................................................... 50 iii List of Figures 1.1. A mountain sunset ........................................................................................... 20 iv List of Tables 1.1. Ordered list numbering scheme by level .......................................................... 10 v List of Examples 1.1. A nested ordered list ........................................................................................ 10 1.2. A basic labeled list ........................................................................................... 12 1.3. A hybrid list ...................................................................................................... 14 1.4. A list with complex content .............................................................................. 16 1.5. A hyperlinked image with caption .................................................................... 20 2.1. Source code with callouts ................................................................................ 33 vi This guide provides a gentle introduction to AsciiDoc1, a plain text documentation syntax and processor. This introduction is intended for anyone who wants to reduce the effort required to write and publish content, whether for technical documentation, articles, web pages or good ol'-fashioned prose. If you want to know what AsciiDoc is all about, find the answer in What is AsciiDoc?2 If you’re looking for a concise survey of the AsciiDoc syntax, consult the AsciiDoc Syntax Quick Reference3. In this guide, you’ll learn: • The basic structure of an AsciiDoc document • How to create your first AsciiDoc document • How to add other structural elements such as lists, block quotes and source code • How to render an AsciiDoc document to HTML, DocBook and PDF In addition to covering the AsciiDoc basics, this guide also suggests a set of conventions to help you create more consistent documents and maximize your writing productivity. Let’s dive in to AsciiDoc! 1 http://asciidoc.org 2 http://asciidoctor.org/docs/what-is-asciidoc-why-use-it 3 http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/ vii Chapter 1. Writing in AsciiDoc The goal of this section is to teach you how to compose your first AsciiDoc document. Hopefully, when you look back, you’ll agree it just makes sense. Your adventure with AsciiDoc begins in your favorite text editor. 1.1. “It’s just text, mate.” Since AsciiDoc syntax is just plain text , you can write an AsciiDoc document using any text editor. You don’t need complex word processing programs like Microsoft Word, OpenOffice Writer or Google Docs. In fact, you shouldn’t use these programs because they add cruft to your document (that you can’t see) and makes conversion tedious. While it’s true any text editor will do, I recommend selecting an editor that supports syntax highlighting for AsciiDoc. The color brings contrast to the text, making it easier to read. The highlighting also confirms when you’ve entered the correct syntax for an inline or block element. The most popular application for editing plain text on Mac OS X is TextMate. A similar choice on Linux is GEdit. On Windows, stay away from Notepad and Wordpad because they produce plain text which is not cross-platform friendly. Opt instead for a competent text editor like Notepad++. If you’re a programmer (or a writer with an inner geek), you’ll likely prefer Vim, Emacs, or Sublime Text, all of which are available cross-platform. The key feature all these editors share is syntax highlighting for AsciiDoc1. Previewing the output of the document while editing can be helpful. To learn how to setup instant preview, check out the Editing AsciiDoc with Live Preview2 tutorial. Open up your favorite text editor and get ready to write some AsciiDoc! 1.2. Content is king! The bulk of the content in an AsciiDoc document is paragraph text. In fact, all it takes to create a document in AsciiDoc is a single sentence. No special markup is required to write