AsciiDoc Frequently Asked Questions

Spaces are not allowed in macro targets so this include macro will not be processed:

The work-around is to replace the spaces with the {sp} (space character) attribute, for example:

Some documents such as specifications and legalese require all paragraphs to be sequentially numbered through the document, and to be able to reference these numbers.

This can be achieved by using the DocBook toolchain but numbering the paragraphs with AsciiDoc using a custom config file containing the following (see https://asciidoc.org/userguide.html#X27 for ways to include such a file):

References to the paragraphs operate in the normal way, you label the paragraph:

and reference it in the normal manner:

The text of the reference will be the paragraph number.

For this to work for HTML you have to generate it via the DocBook toolchain.

DocBook is a content and structure markup language, therefore AsciiDoc generated DocBook markup is also limited to content and structure. Layout and formatting definition is specific to the DocBook toolchain.

The dblatex toolchain can be configured by setting parameters defined at http://dblatex.sourceforge.net/doc/manual/sec-params.html or for more complex styling by custom Latex stylesheets described at http://dblatex.sourceforge.net/doc/manual/sec-custom-latex.html.

Similarly FOP can be configured by parameters described at http://sagehill.net/docbookxsl/OptionsPart.html and with custom xsl stylesheets generating formatting objects as described at http://sagehill.net/docbookxsl/CustomizingPart.html.

This is a two step process:

+ (plus) quoted text is implemented as an AsciiDoc quotes whereas ` (grave accent or backtick) quoted text is implemented as an AsciiDoc inline literal passthrough macro. The semantics are different:

Probably because your document title contains formatting that has generated HTML title markup. You can resolve this by explicitly defining the title attribute in your document’s header.

AsciiDoc is backend agnostic, the asciidoc command has no knowledge of the syntax or structure of the backend format that it generates. Output document validation (syntactic and structural) should be performed separately by external validation tools. For example, AsciiDoc’s a2x toolchain command automatically performs validation checks using xmllint.

DocBook has no provision for specifying table of contents levels but you can set the TOC level further down the toolchain by passing the DocBook XSL Stylesheets toc.section.depth parameter to dblatex (using the --param option) or xsltproc (using the --stringparam option). For example to show only chapter titles in the TOC of a book document set toc.section.depth to 0. Increment the toc.section.depth value to show more sub-section titles. If you are using a2x you can set the options in the source file, for example:

If the document is of type article use the value 1 to show only top level section titles in the TOC, use the value 2 for two levels etc.

DocBook outputs processed by DocBook XSL Stylesheets (either manually or via a2x) can generate additional separate section and chapter tables of contents using combinations of the TOC parameters. Here are some examples using combinations of the generate.section.toc.level and toc.section.depth DocBook XSL Stylesheets parameters:

You can customize the appearance of an EPUB document with CSS. See the Sherlock Holmes eBook example on the AsciiDoc website.

The docinfo, docinfo1 and docinfo2 attributes allow you include document information files containing DocBook XML into the header of the output file.

If you go the DocBook route then yes — just omit the caption from the AsciiDoc xref (<<...>>) macro. Both dblatex and DocBook XSL will use the target element’s title text. Examples:

The AsciiDoc reftext attribute has been used to explicitly set the link text to 2nd section for Section Two.

In addition to the built-in styles you can define your own. This (simplified) example for HTML backends defines a table style called red which sets the background cell color to red. First put the definition in a configuration file:

Now you can use the style name to style cells or columns (in this example we use an unambiguous shortened abbreviation r):

Both block and inline comment lines are displayed on the output if the showcomments attribute is defined. Example:

Is rendered as:

Qui in magna commodo, est labitur dolorum an. Est ne magna primis
An inline comment line.
adolescens.

The .txt text file extension is preferred, but it’s just a convention and it’s not enforced by the software.

AsciiDoc source files are human readable plain text files which is what the .txt extension is for. All text editors recognize and open files with a .txt extension. The .txt extension is universally recognized and unambiguous — you are not left asking questions like “What on earth is this file with the funny extension?”, “How do I open it?” and “Is it safe to open?”.

If your outputs are DocBook generated then adding the following inline macro to a custom configuration file will result in auto-incrementing bibliography entry numbers (instead of displaying the bibliographic identifiers):

This FAQ submitted by Bela Hausmann.

A line of four or more dashes will be mistaken for the ListingBlock terminator, one way round this problem is to use a LiteralBlock styled as a listing block. For example:

There are a number of dblatex XSL parameters that can be used to customize PDF output. You can set them globally in the AsciiDoc ./dblatex/asciidoc-dblatex.xsl configuration file or you can also pass them on the a2x(1) command-line. Here are some examples:

The latex.output.revhistory parameter is used to suppress the revision history:

The doc.layout parameter is used to include the cover page and document body (i.e. excludes table of contents and index), the doc.publisher.show parameter is used to exclude the cover page logo:

See also the dblatex XSL parameter reference.

Set the doc.lot.show XSL parameter — you can set it using the dblatex --param command-line option, for example:

You could simply omit the document title, but this will result in a blank title element in HTML outputs. If you want the HTML title element to contain the document title then define the notitle attribute (this will just suppress displaying the title), for example:

The following example expands the image inline macro, but the expansion contains double-quote characters which confuses the ensuing footnoteref macro expansion:

The solution is to use unquoted attribute values, replacing embedded commas with the comma character entity (,):

Similarly, you can embed double-quote characters in unquoted attribute values using the " character entity.

Not all valid AsciiDoc source generates valid DocBook, for example special sections (abstract, preface, colophon, dedication, bibliography, glossary, appendix, index, synopsis) have different DocBook schema’s to normal document sections. For example, a paragraph is illegal in a bibliography.

Don’t forget if your document is a book you need to specify the asciidoc -d book command option, if you don’t an article DocBook document will be generated, possibly containing book specific sections, resulting in validation errors.

For example, you want to use References as a normal section name but AsciiDoc is auto-magically generating a DocBook bibliography section. All you need to do is explicitly specify the section template name, for example:

Use an inline or block passthrough macros. This example inserts <?dblatex bgcolor="#cceeff"?> into the DocBook output generated by AsciiDoc:

Mixing doubled-quoted text with inline literal passthroughs can produce undesired results, for example, all of the following line is interpreted as an inline literal passthrough:

In this case the solution is to use monospace quoting instead of the inline literal:

Use the pass:[] macro if it’s necessary to suppress substitutions in the monospaced text, for example:

With the advent of Internet Explorer 8 all major web browsers now support the data URI scheme for embedded images. The AsciiDoc xhtml11 and html5 backends supports the data URI scheme for embedded images and by default it embeds the CSS stylesheet. For example the following command will generate a single article.html file containing embedded images, admonition icons and the CSS stylesheet:

AsciiDoc has a built-in trace mechanism which is controlled by the trace attribute; there is also the --verbose command-line option. These features are detailed in Appendix G of the User Guide.

This is the response to a question posted on the AsciiDoc discussion list, it illustrates a number of useful techniques. The question arose because the source highlight filter language identifier for the C++ language is c++ when generating PDFs via dblatex (LaTeX listings package) or cpp when generating HTML (GNU source-highlight).

Using straight ifdef::[] block macros we have:

This can be shortened using the short form of the ifdef::[] macro:

Using a conditional attribute instead of the ifdef::[] macro is even shorter:

If you have a number of listings it makes sense to factor the conditional attribute to a normal attribute:

Even shorter, set the default source highlight filter language attribute so you don’t have to specify it every time:

Most likely the passthrough encloses another passthrough with a higher precedence. For example trying to render this pass:[] with this `pass:[]` results in a blank string because the pass:[] passthrough evaluates first, instead use monospaced quoting and escape the passthrough i.e. +\pass:[]+

You can’t use a BlockId block element inside a list but you can use the syntactically identical anchor inline macro. For example:

This will not work:

If you place two lists with different syntax hard up against each other then the second list will be nested in the first. If you don’t want the second list to be nested separate them with a comment line block macro. For example:

There are a number of programs available that generate presentation charts from textual specification, for example Pychart is a library for writing chart scripts in Python. Here’s an example from the Pychart documentation:

To execute the script and include the generated chart image in your document add the following lines to the AsciiDoc source:

Styling is backend dependent:

You can set the grid and frame attributes globally in your document header with Attribute Entries or from the command-line using the --attribute option. In the following example tables that don’t explicitly set the grid and frame values will default to all and topbot respectively:

Use the predefined {backslash} attribute reference instead of an actual backslash, for example if the {projectname} attribute has the value foobar then:

would be rendered as:

Most AsciiDoc inline elements can be suppressed by preceding them with a backslash character. These elements include:

But there are exceptions — see the next question.

There are a number of exceptions to the usual single backslash rule — mostly relating to URL macros that have two syntaxes or quoting ambiguity. Here are some non-standard escape examples:

The source of this problem is ambiguity across substitution types — the first match unescapes allowing the second to substitute. A work-around for difficult cases is to side-step the problem using the pass:[] passthrough inline macro.

Here’s how to handle situations where the first line of a paragraph is mistaken for a list item.

Precede the bullet or index of the first list item with an {empty} attribute, for example:

The predefined {empty} attribute is replaced by an empty string and ensures the first line is not mistaken for a bulleted list item.

Two colons or semicolons in a paragraph may be confused with a labeled list entry. Use the predefined {two-colons} and {two-semicolons} attributes to suppress this behavior, for example:

Will be rendered as:

Qui in magna commodo:: est labitur dolorum an. Est ne magna primis adolescens.

You can set the element’s style entry in a global or custom configuration file.

This example this will horizontally style all labeled lists that don’t have an explicit style attribute:

This example will put a top and bottom border on all tables that don’t already have an explicit style attribute:

Alternatively you can set the configuration entries from inside your document, the above examples are equivalent to:

An error was returned when AsciiDoc tried to execute an external filter command. The most common reason for this is that the filter command could not be found by the command shell. To figure out what the problem is run AsciiDoc with the --verbose option to determine the command that is failing and then try to run the command manually from the command-line.

Yelp, the GNOME help viewer, does a creditable job of displaying DocBook XML files directly.

LibreOffice can convert HTML produced by AsciiDoc to ODF text format and PDF format (I used LibreOffice 3.5 at the time of writing, the fidelity is very good but it’s not perfect):

Alternatively you could manually copy-and-paste the entire document from a Web browser into a blank ODF document in LibreOffice — this technique will bring through the table of contents and footnotes.

This tip was originally contributed by Bernard Amade.

Use the {include:} system attribute instead of the include::[] macro (the former is not expanded until after the table data has been parsed into cells, whereas the latter is included before the table is processed.

Apply the The verse paragraph style, the rendered text preserves line boundaries and is useful for lyrics and poems. For example:

Alternatively, if you are generating PDF files, you can use line breaks. For example:

Use the non-breaking space character entity reference   (see the next question). You could also use the predefined {nbsp} attribute reference.

Yes, just enter the reference in your document. For example β will print a Greek small beta character β

URL inline macro targets (addresses) cannot contain white space characters. If you need spaces encode them as %20. For example:

Set the AsciiDoc lang attribute to the appropriate language code. For example:

This will ensure that downstream DocBook processing will generate the correct language specific document headings (things like table of contents, revision history, figure and table captions, admonition captions).

For HTML outputs set the caption attribute to an empty string, either globally:

or on an element by element basis, for example:

A quick way to do this is put both authors in a single first name, for example:

asciidoc(1) replaces the underscores with spaces.

If you are generating DocBook then a more flexible approach is to create a docinfo file containing a DocBook authorgroup element (search the User Guide for docinfo for more details).

Omitting the tag name will disable quoting. For example, if you don’t want superscripts or subscripts then put the following in a custom configuration file or edit the global asciidoc.conf configuration file:

Alternatively you can set the configuration entries from within your document, the above examples are equivalent to:

The default format for the {localdate} attribute is the ISO 8601 yyyy-mm-dd format. You can change this format by explicitly setting the {localdate} attribute. For example by setting it using the asciidoc(1) -a command-line option:

You could also set it by adding an Attribute Entry to your source document, for example:

The User Guide has some. You could also look at ./doc/main.aap and ./examples/website/main.aap in the AsciiDoc distribution, they have all the commands used to build the AsciiDoc documentation and the AsciiDoc website (even if you don’t use A-A-P you’ll still find it useful).

<simpara> is really the same as <para> except it can’t contain block elements — this matches, more closely, the AsciiDoc paragraph semantics.

By default only specialcharacters and callouts are substituted in listing blocks; you can add quotes substitutions by explicitly setting the block subs attribute, for example:

The -al will rendered bold. Note that:

Alternative, if the lines are contiguous, you could use the literal paragraph style:

Internally the include1 macro is translated to the include1 system attribute which means it must be evaluated in a region where attribute substitution is enabled. include1 won’t work, for example, in a ListingBlock (unless attribute substitution is enabled). include1 is intended for use in configuration files, use the include macro and set the attribute depth=1 instead, for example:

For the AsciiDoc mailto macro to work with multiple email addresses (as per RFC2368) you need to URL encode the @ characters (replace them with %40), if you don’t the individual addresses will be rendered as separate links. You also need to replace spaces with %20.

For example, the following call won’t work:

Use this instead:

Quote the entry name — this nonsensical example replaces x\ with y:

If quoting were omitted the equals character (separating the entry name x from the value y) would be escaped.

Here are some techniques you can use to control page breaks in HTML outputs produced by the xhtml11 and html5 backends:

By default the xhtml11 and html5 backends auto-position the TOC after the header. You can manually position the TOC by setting the toc-placement attribute value to manual and then inserting the toc::[] block macro where you want the TOC to appear. For example, put this in the document header:

The put this where you want the TOC to appear:

You can set the maximum with for outputs generated by html5, xhtml11 and slidy backends by assigning the max-width attribute (either from the command-line or with an attribute entry in the document header). For example:

Some applications require mixing fonts beyond the set of faces normally provided by default (normal, monospace, italic etc.) for example mixed language text where the font used for the majority of text does not contain suitable glyphs in the minority language.

As AsciiDoc can not provide presentation markup since it is not provided by Docbook this is achieved by marking text which should use a different font with a custom role which can be rendered by the the docbook toolchain.

The Docbook toolchains will have to be configured to render the text that you mark with the custom role.

For FOP a small XSL wrapper is needed, say a file called my_fo.xsl containing:

This is used with a2x by:

and the AsciiDoc source marked by:

Thanks to Antonio Borneo for this answer.

A closing quote is not recognised if it is immediately followed by a letter (the f in footnote in the following example):

A workaround is to put a word-joiner between the trailing quote and the footnote (the {empty} attribute would also work), for example:

You can use Pandoc to convert documents in markdown, reStructuredText, textile, HTML, DocBook, or LaTeX to AsciiDoc.

a2x generates HTML via DocBook (DocBook XSL Stylesheets) so if you use a passthrough block it must contain DocBook (not HTML). Fortunately DocBook XSL Stylesheets has a dbhtml-include processing instruction which will include a file containing raw HTML into the generated HTML output. For example:

If your document has blocks that have block titles, you may notice in the PDF output (generated by a2x(1) using the --fop flag) that a period gets added to the end of the block title.

You will not see the period in the intermediary DocBook XML that’s generated when creating a PDF — it’s added by the DocBook XSL templates when the DocBook XML is converted to FO XML.

The DocBook XSL attribute that controls what character is added after a block title is runinhead.default.title.end.punct. You can override it and eliminate the default period value by adding the following line to the ./docbook-xsl/common.xsl file that ships with AsciiDoc:

This FAQ was contributed by Dan Allen.