Skip to content. | Skip to navigation

Personal tools
You are here: Home Operations Web site documentation Using AsciiDoc to create XHTML documents

Using AsciiDoc to create XHTML documents

What is AsciiDoc?

AsciiDoc is a lightweight markup language for text documents with a simple, natural syntax. AsciiDoc documents are readable in their plain text form, but can also be translated to a various presentation formats, such as XHTML and PDF. If you are not comfortable editing text documents containing markup, or using the UNIX command line, you should probably create content using the Plone web interface and the page editor built into Plone instead.

How do I install AsciiDoc?

Mac OS X

Instructions for installing AsciiDoc in Mac OS X can be found in my Mac software install instructions.

Linux

Installing AsciiDoc in Linux should be similar to Mac OS X. Your Linux distribution may also include a prepackaged version of AsciiDoc.

Windows

I have not attempted to install AsciiDoc in Windows. It would be considerably more difficult to install and use in Windows, since Python is not included in Windows by default, and the Windows command line is very different from UNIX.

Tip To get started with AsciiDoc and XHTML, you only need to install the AsciiDoc software package; the rest of the packages are for more advanced uses, such as creating PDF files.

What does an AsciiDoc document look like?

This is a brief outline of how to use the most common AsciiDoc syntax to create a document. Complete documentation of AsciiDoc syntax is available at the AsciiDoc web site.

Tip The AsciiDoc web site was created using AsciiDoc, and the page source for any page in the site is available through a “Page Source” link in the left column. This document was also written in AsciiDoc, and its page source is also available.

Document header

An AsciiDoc document starts with a document header, containing the title of the document and information about the author and document version.

Example: The header of this document
Using AsciiDoc to create XHTML documents
========================================
Glenn Eychaner <geychaner@lco.cl>
version 1.5, December 2008
:icons:

The last line of this header is an attribute that tells AsciiDoc to use icons instead of text in admonitions.

Sections and subsections

An AsciiDoc document is divided into sections and subsections. Each section has a title, which can be a two line title or a one line title. I generally use a two line title in the document header and one line titles elsewhere, because I find it easier to remember the syntax of the one line title; place a number of equals signs on either side of the title equal to the section level of the title plus one.

Example: Level one and level two section titles from this document
== What does an AsciiDoc document look like? ==
=== Document header ===

Sections can be nested up to four levels, and can be numbered by adding the :numbered: attribute to the header of the document.

Document content

The actual content of the document is contained in a series of paragraphs and blocks containing the actual text. Paragraphs are separated by blank lines, while blocks are surrounded by leading and trailing lines of delimiter characters. The most commonly used paragraphs and blocks are:

  • Simple paragraphs, which are blocks of text that begin and end with a blank line. These paragraphs are never indented.

  • Literal paragraphs, in which each line is indented by one or more spaces or tabs. Literal paragraphs are rendered in a monospace font with no formatting or substitutions.

  • Bulleted and numbered lists, like this one, in which each item begins with a bullet or number. Items in a list can be more than one line long.

  • Listing blocks, which are often used to include code blocks in a document. Listing blocks begin and end with a line of dash characters.

Each paragraph or block can have a title, on a single line at the top of the paragraph or block, and starting with a single period.

Text formatting

Words and phrases in an AsciiDoc document can be formatted in many ways.

Example: AsciiDoc formatting
italics

Enclose text in 'apostrophes' or _underlines_. Often used for menu items or file names.

boldface

Enclose text in *asterisks*.

monospaced

Enclose text in `grave accents` or +plus characters+. Often used for text to be typed or keys to be pressed.

‘single quoted’

Place `a grave accent at the left and an apostrophe at the right'.

“double quoted”

Place ``two grave accents at the left and two apostrophes at the right''.

In addition to formatting words and phrases (which are be bounded by white space or punctuation), arbitrary text can be formatted by doubling the formatting markup. Text formats can be nested (which often requires using the arbitrary formatting syntax), but cannot partially overlap.

Example: Arbitrary, nested and invalid overlapping formatting
First Character Boldface

**F**irst **C**haracter **B**oldface

“quoted monospaced boldface italic text”

_**++``quoted monospaced boldface italic text''++**_

Invalid overlapping formatting

*bold _and* italic_ overlapping

AsciiDoc also has a number of other less commonly used formatting options, such as superscripts, subscripts, and even colored text.

Links, cross-references, and images are implemented as macros in the AsciiDoc language. The documentation makes them sound more complicated than they actually are.

Links

Links to URLs are easy to include in an AsciiDoc document; simply include the URL, followed immediately by sqaure brackets containing the text that should appear as the link. For example, http://www.lco.cl/[LCO Home Page] renders as a link to the LCO Home Page. When linking to a local document (on the same Web server or file system), replace the URL with use link: followed by the relative path to the document. For example, link:./Using%20AsciiDoc.txt[source] links to the AsciiDoc source for this document, which happens to be in the same directory as this document.

Images

The syntax for including images in a document is similar to links to local documents; for example, image:/print_icon.gif[printer] embeds the little printer image (from the upper right of the LCO web pages) directly in the text. Figures and other large images, however, are best included as block images, which can have titles and other attributes like any other block or paragraph. For example:

Example: Block image
.LCO Logo
[caption="Image 1: "]
image::/logo.jpg[LCO Logo]
LCO Logo
Image 1: LCO Logo
Cross-references

Cross-references are links in a document to other parts of the same document. First, you must create an anchor within the document by enclosing an anchor name in double square brackets, for example, [[here]]. The anchor won’t render as anything in the document, but elsewhere in the document you can create a link to it by enclosing the anchor name and the text that should appear as the link in double angle brackets, for example, <<here,Go There!>>, which renders as Go There!.

How do I edit an AsciiDoc document?

You can edit an AsciiDoc document in any text editor you choose. Filenames of AsciiDoc documents should end in .txt, though this is not required.

Caution
Text Encodings and Line Endings
Make sure your document is saved in an ASCII-compatible text encoding with UNIX line endings. For example, in TextWrangler (a popular text editor on the Mac) the encoding and line endings can be set using Edit⇒Document Options. The UTF-8 (no BOM) text encoding is recommended for documents to be published on the Plone server.

How do I view an AsciiDoc document as XHTML?

Once you have created an AsciiDoc document, open a Terminal window and run the following command, substituting the (fully qualified) name of the AsciiDoc file you want to view for [filename]:

asciidoc --unsafe -a linkcss -a stylesdir=/usr/local/etc/asciidoc/stylesheets \
        -a iconsdir=/usr/local/etc/asciidoc/images/icons [filename]

This will produce an XHTML file in the same directory as the AsciiDoc file. The XHTML file will have the same name as the AsciiDoc file but with the ending changed to .html, and can be viewed in a web browser by double-clicking on it.

How do I view an AsciiDoc document as a PDF?

First, if you have not done so already, you will need to install the AsciiDoc DocBook utilities, as detailed in my Mac software install instructions. After installing the utilities, you can create a PDF from an AsciiDoc document with the command:

a2x -f pdf [filename]

The PDF is created by using the asciidoc command to transform the AsciiDoc file to a DocBook file, and then using the DocBook utilities to transform it to PDF. There are a large number of options that can be passed to a2x and the DocBook utilities, which are detailed in the documentation for a2x and the individual DocBook utilities.

The a2x command can also be used to produce several other output formats, including XHTML, PostScript, plain text, and LaTeX.

How do I publish an AsciiDoc document on the Plone server?

Processing the file into XHTML suitable for the Plone server

To format an AsciiDoc file for publishing on the Plone server, first open a Terminal window and run the following command:

asciidoc -s --unsafe -a iconsdir=/lco/portal_skins/plone_images/asciidoc [filename]

This will convert the file to an XHTML file with the header and footer removed. (As a result, the file will no longer look correct in a Web browser. Do not be alarmed.) In order for the AsciiDoc formatting to be rendered properly in the Plone server, the file must then have a <div class="asciidoc"> tag added to the top of the file, and a corresponding </div> tag added to the bottom. The XHTML file is now ready to be published on the Plone server.

Publishing the XHTML file

The simplest way to publish the XHTML file on the Plone web server is to use the Plone web interface to create a page in the server, and then cut-and-paste the processed file into the source view for the page. You will also have to copy the first line of the original AsciiDoc source document into the title field in the web interface.

If you are comfortable with the UNIX command line and programs such as ftp, you can publish documents to the Plone web server using WebDAV. You will need Herman Rojas to enable WebDAV access to the Plone server for you.

After you publish your document to the web server, you will have to edit other pages in the web server to link to your document; these pages will usually not be AsciiDoc or WebDAV pages, and will be edited using the Plone web interface.

Document Actions