This guide provides a gentle introduction to AsciiDoc, 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.
|
Tip
|
If you want to know what AsciiDoc is all about, find the answer in What is AsciiDoc? If you’re looking for a concise survey of the AsciiDoc syntax, consult the AsciiDoc Syntax Quick Reference. |
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!
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.
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.
|
Tip
|
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 AsciiDoc.
|
Tip
|
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 Preview tutorial. |
Open up your favorite text editor and get ready to write some AsciiDoc!