- 1. Introduction
- 2. Getting Started
- 3. AsciiDoc Document Types
- 4. AsciiDoc Backends
- 5. DocBook
- 6. Generating Plain Text Files
- 7. HTML5 and XHTML 1.1
- 8. Document Structure
- 9. Document Processing
- 10. Text Formatting
- 11. Titles
- 12. Block Titles
- 13. BlockId Element
- 14. AttributeList Element
- 15. Paragraphs
- 16. Delimited Blocks
- 17. Lists
- 18. Footnotes
- 19. Indexes
- 20. Callouts
- 21. Macros
AsciiDoc is a text document format for writing notes, documentation, articles, books, ebooks, slideshows, web pages, blogs and UNIX man pages. AsciiDoc files can be translated to many formats including HTML, PDF, EPUB, man page. AsciiDoc is highly configurable: both the AsciiDoc source file syntax and the backend output markups (which can be almost any type of SGML/XML markup) can be customized and extended by the user.
|
Warning
|
This user guide is for AsciiDoc.py, which is a legacy processor for this syntax, handling an older rendition of AsciiDoc. As such, this will not properly handle the current AsciiDoc specification. It is suggested that unless you specifically require the AsciiDoc.py toolchain, you should find a processor that handles the modern AsciiDoc syntax. |
This is an overly large document, it probably needs to be refactored into a Tutorial, Quick Reference and Formal Reference.
If you’re new to AsciiDoc read this section and the Getting
Started section and take a look at the example AsciiDoc (*.txt)
source files in the distribution doc directory.
AsciiDoc is a plain text human readable/writable document format that can be translated to DocBook or HTML using the asciidoc(1) command. You can then either use asciidoc(1) generated HTML directly or run asciidoc(1) DocBook output through your favorite DocBook toolchain or use the AsciiDoc a2x(1) toolchain wrapper to produce PDF, EPUB, DVI, LaTeX, PostScript, man page, HTML and text formats.
The AsciiDoc format is a useful presentation format in its own right: AsciiDoc markup is simple, intuitive and as such is easily proofed and edited.
AsciiDoc is light weight: it consists of a single Python script and a bunch of configuration files. Apart from asciidoc(1) and a Python interpreter, no other programs are required to convert AsciiDoc text files to DocBook or HTML. See Example AsciiDoc Documents below.
Text markup conventions tend to be a matter of (often strong) personal preference: if the default syntax is not to your liking you can define your own by editing the text based asciidoc(1) configuration files. You can also create configuration files to translate AsciiDoc documents to almost any SGML/XML markup.
asciidoc(1) comes with a set of configuration files to translate AsciiDoc articles, books and man pages to HTML or DocBook backend formats.
DocBook has emerged as the de facto standard Open Source documentation format. But DocBook is a complex language, the markup is difficult to read and even more difficult to write directly — I found I was spending more time typing markup tags, consulting reference manuals and fixing syntax errors, than I was writing the documentation.
See the README and INSTALL files for install prerequisites and
procedures. Packagers take a look at Packager Notes.
The best way to quickly get a feel for AsciiDoc is to view the AsciiDoc web site and/or distributed examples:
-
Take a look at the linked examples on the AsciiDoc web site home page https://asciidoc.org/. Press the Page Source sidebar menu item to view corresponding AsciiDoc source.
-
Read the
*.txtsource files in the distribution./docdirectory along with the corresponding HTML and DocBook XML files.
There are three types of AsciiDoc documents: article, book and manpage. All document types share the same AsciiDoc format with some minor variations. If you are familiar with DocBook you will have noticed that AsciiDoc document types correspond to the same-named DocBook document types.
Use the asciidoc(1) -d (--doctype) option to specify the AsciiDoc
document type — the default document type is article.
By convention the .txt file extension is used for AsciiDoc document
source files.
Used for short documents, articles and general documentation. See the
AsciiDoc distribution ./doc/article.txt example.
AsciiDoc defines standard DocBook article frontmatter and backmatter section markup templates (appendix, abstract, bibliography, glossary, index).
Books share the same format as articles, with the following differences:
-
The part titles in multi-part books are top level titles (same level as book title).
-
Some sections are book specific e.g. preface and colophon.
Book documents will normally be used to produce DocBook output since DocBook processors can automatically generate footnotes, table of contents, list of tables, list of figures, list of examples and indexes.
AsciiDoc defines standard DocBook book frontmatter and backmatter section markup templates (appendix, dedication, preface, bibliography, glossary, index, colophon).
- Book
-
The
./doc/book.txtfile in the AsciiDoc distribution. - Multi-part book
-
The
./doc/book-multi.txtfile in the AsciiDoc distribution.
Used to generate roff format UNIX manual pages. AsciiDoc manpage documents observe special header title and section naming conventions — see the Manpage Documents section for details.
AsciiDoc defines the synopsis section markup template to
generate the DocBook refsynopsisdiv section.
See also the asciidoc(1) man page source (./doc/asciidoc.1.txt) from
the AsciiDoc distribution.
The asciidoc(1) command translates an AsciiDoc formatted file to the
backend format specified by the -b (--backend) command-line
option. asciidoc(1) itself has little intrinsic knowledge of backend
formats, all translation rules are contained in customizable cascading
configuration files. Backend specific attributes are listed in the
Backend Attributes section.
- docbook45
-
Outputs DocBook XML 4.5 markup.
- docbook5
-
Outputs DocBook XML 5.0 markup.
- html4
-
This backend generates plain HTML 4.01 Transitional markup.
- xhtml11
-
This backend generates XHTML 1.1 markup styled with CSS2. Output files have an
.htmlextension. - html5
-
This backend generates HTML 5 markup, apart from the inclusion of audio and video block macros it is functionally identical to the xhtml11 backend.
- slidy
-
Use this backend to generate self-contained Slidy HTML slideshows for your web browser from AsciiDoc documents. The Slidy backend is documented in the distribution
doc/slidy.txtfile and online. - wordpress
-
A minor variant of the html4 backend to support blogpost.
- latex
-
Experimental LaTeX backend.
Backend aliases are alternative names for AsciiDoc backends. AsciiDoc comes with two backend aliases: html (aliased to xhtml11) and docbook (aliased to docbook45).
You can assign (or reassign) backend aliases by setting an AsciiDoc
attribute named like backend-alias-<alias> to an AsciiDoc backend
name. For example, the following backend alias attribute definitions
appear in the [attributes] section of the global asciidoc.conf
configuration file:
backend-alias-html=xhtml11 backend-alias-docbook=docbook45
The asciidoc(1) --backend option is also used to install and manage
backend plugins.
-
A backend plugin is used just like the built-in backends.
-
Backend plugins take precedence over built-in backends with the same name.
-
You can use the
{asciidoc-confdir}intrinsic attribute to refer to the built-in backend configuration file location from backend plugin configuration files. -
You can use the
{backend-confdir}intrinsic attribute to refer to the backend plugin configuration file location. -
By default backends plugins are installed in
$HOME/.asciidoc/backends/<backend>where<backend>is the backend name.
AsciiDoc generates article, book and refentry DocBook documents (corresponding to the AsciiDoc article, book and manpage document types).
Most Linux distributions come with conversion tools (collectively called a toolchain) for converting DocBook files to presentation formats such as Postscript, HTML, PDF, EPUB, DVI, PostScript, LaTeX, roff (the native man page format), HTMLHelp, JavaHelp and text. There are also programs that allow you to view DocBook files directly, for example Yelp (the GNOME help viewer).
DocBook files are validated, parsed and translated various presentation file formats using a combination of applications collectively called a DocBook tool chain. The function of a tool chain is to read the DocBook markup (produced by AsciiDoc) and transform it to a presentation format (for example HTML, PDF, HTML Help, EPUB, DVI, PostScript, LaTeX).
A wide range of user output format requirements coupled with a choice of available tools and stylesheets results in many valid tool chain combinations.
One of the biggest hurdles for new users is installing, configuring
and using a DocBook XML toolchain. a2x(1) can help — it’s a
toolchain wrapper command that will generate XHTML (chunked and
unchunked), PDF, EPUB, DVI, PS, LaTeX, man page, HTML Help and text
file outputs from an AsciiDoc text file. a2x(1) does all the grunt
work associated with generating and sequencing the toolchain commands
and managing intermediate and output files. a2x(1) also optionally
deploys admonition and navigation icons and a CSS stylesheet. See the
a2x(1) man page for more details. In addition to asciidoc(1) you
also need xsltproc(1), DocBook XSL Stylesheets and
optionally: dblatex or FOP (to generate PDF);
w3m(1) or lynx(1) (to generate text).
The following examples generate doc/source-highlight-filter.pdf from
the AsciiDoc doc/source-highlight-filter.txt source file. The first
example uses dblatex(1) (the default PDF generator) the second
example forces FOP to be used:
$ a2x -f pdf doc/source-highlight-filter.txt $ a2x -f pdf --fop doc/source-highlight-filter.txt
See the a2x(1) man page for details.
|
Tip
|
Use the --verbose command-line option to view executed
toolchain commands.
|
AsciiDoc produces nicely styled HTML directly without requiring a DocBook toolchain but there are also advantages in going the DocBook route:
-
HTML from DocBook can optionally include automatically generated indexes, tables of contents, footnotes, lists of figures and tables.
-
DocBook toolchains can also (optionally) generate separate (chunked) linked HTML pages for each document section.
-
Toolchain processing performs link and document validity checks.
-
If the DocBook lang attribute is set then things like table of contents, figure and table captions and admonition captions will be output in the specified language (setting the AsciiDoc lang attribute sets the DocBook lang attribute).
On the other hand, HTML output directly from AsciiDoc is much faster, is easily customized and can be used in situations where there is no suitable DocBook toolchain (for example, see the AsciiDoc website).
-
dblatex is easier to install, there’s zero configuration required and no Java VM to install — it just works out of the box.
-
dblatex source code highlighting and numbering is superb.
-
dblatex is easier to use as it converts DocBook directly to PDF whereas before using FOP you have to convert DocBook to XML-FO using DocBook XSL Stylesheets.
-
FOP is more feature complete (for example, callouts are processed inside literal layouts) and arguably produces nicer looking output.
-
Convert DocBook XML documents to HTML Help compiler source files using DocBook XSL Stylesheets and xsltproc(1).
-
Convert the HTML Help source (
.hhpand.html) files to HTML Help (.chm) files using the Microsoft HTML Help Compiler.
- AsciiDoc
-
Converts AsciiDoc (
.txt) files to DocBook XML (.xml) files. - DocBook XSLT Stylesheets
-
These are a set of XSL stylesheets containing rules for converting DocBook XML documents to HTML, XSL-FO, manpage and HTML Help files. The stylesheets are used in conjunction with an XML parser such as xsltproc(1).
- xsltproc
-
An XML parser for applying XSLT stylesheets (in our case the DocBook XSL Stylesheets) to XML documents.
- dblatex
-
Generates PDF, DVI, PostScript and LaTeX formats directly from DocBook source via the intermediate LaTeX typesetting language — uses DocBook XSL Stylesheets, xsltproc(1) and
latex(1). - FOP
-
The Apache Formatting Objects Processor converts XSL-FO (
.fo) files to PDF files. The XSL-FO files are generated from DocBook source files using DocBook XSL Stylesheets and xsltproc(1). - Microsoft Help Compiler
-
The Microsoft HTML Help Compiler (
hhc.exe) is a command-line tool that converts HTML Help source files to a single HTML Help (.chm) file. It runs on MS Windows platforms and can be downloaded from https://www.microsoft.com/.
You will have noticed that the distributed HTML and HTML Help
documentation files (for example ./doc/asciidoc.html) are not the
plain outputs produced using the default DocBook XSL Stylesheets
configuration. This is because they have been processed using
customized DocBook XSL Stylesheets along with (in the case of HTML
outputs) the custom ./stylesheets/docbook-xsl.css CSS stylesheet.
You’ll find the customized DocBook XSL drivers along with additional
documentation in the distribution ./docbook-xsl directory. The
examples that follow are executed from the distribution documentation
(./doc) directory. These drivers are also used by a2x(1).
common.xsl-
Shared driver parameters. This file is not used directly but is included in all the following drivers.
chunked.xsl-
Generate chunked XHTML (separate HTML pages for each document section) in the
./doc/chunkeddirectory. For example:$ python ../asciidoc.py -b docbook asciidoc.txt $ xsltproc --nonet ../docbook-xsl/chunked.xsl asciidoc.xml
epub.xsl-
Used by a2x(1) to generate EPUB formatted documents.
fo.xsl-
Generate XSL Formatting Object (
.fo) files for subsequent PDF file generation using FOP. For example:$ python ../asciidoc.py -b docbook article.txt $ xsltproc --nonet ../docbook-xsl/fo.xsl article.xml > article.fo $ fop article.fo article.pdf
htmlhelp.xsl-
Generate Microsoft HTML Help source files for the MS HTML Help Compiler in the
./doc/htmlhelpdirectory. This example is run on MS Windows from a Cygwin shell prompt:$ python ../asciidoc.py -b docbook asciidoc.txt $ xsltproc --nonet ../docbook-xsl/htmlhelp.xsl asciidoc.xml $ c:/Program\ Files/HTML\ Help\ Workshop/hhc.exe htmlhelp.hhp
manpage.xsl-
Generate a
roff(1)format UNIX man page from a DocBook XML refentry document. This example generates anasciidoc.1man page file:$ python ../asciidoc.py -d manpage -b docbook asciidoc.1.txt $ xsltproc --nonet ../docbook-xsl/manpage.xsl asciidoc.1.xml
xhtml.xsl-
Convert a DocBook XML file to a single XHTML file. For example:
$ python ../asciidoc.py -b docbook asciidoc.txt $ xsltproc --nonet ../docbook-xsl/xhtml.xsl asciidoc.xml > asciidoc.html
If you want to see how the complete documentation set is processed
take a look at the A-A-P script ./doc/main.aap.
AsciiDoc does not have a text backend (for most purposes AsciiDoc source text is fine), however you can convert AsciiDoc text files to formatted text using the AsciiDoc a2x(1) toolchain wrapper utility.
The xhtml11 and html5 backends embed or link CSS and JavaScript files in their outputs, there is also a themes plugin framework.
-
If the AsciiDoc linkcss attribute is defined then CSS and JavaScript files are linked to the output document, otherwise they are embedded (the default behavior).
-
The default locations for CSS and JavaScript files can be changed by setting the AsciiDoc stylesdir and scriptsdir attributes respectively.
-
The default locations for embedded and linked files differ and are calculated at different times — embedded files are loaded when asciidoc(1) generates the output document, linked files are loaded by the browser when the user views the output document.
-
Embedded files are automatically inserted in the output files but you need to manually copy linked CSS and Javascript files from AsciiDoc configuration directories to the correct location relative to the output document.
| stylesdir attribute | Linked location (linkcss attribute defined) | Embedded location (linkcss attribute undefined) |
|---|---|---|
Undefined (default). |
Same directory as the output document. |
|
Absolute or relative directory name. |
Absolute or relative to the output document. |
Absolute or relative to the AsciiDoc configuration directory (the directory containing the backend conf file). |
| scriptsdir attribute | Linked location (linkcss attribute defined) | Embedded location (linkcss attribute undefined) |
|---|---|---|
Undefined (default). |
Same directory as the output document. |
|
Absolute or relative directory name. |
Absolute or relative to the output document. |
Absolute or relative to the AsciiDoc configuration directory (the directory containing the backend conf file). |
The AsciiDoc theme attribute is used to select an alternative CSS stylesheet and to optionally include additional JavaScript code.
-
Theme files reside in an AsciiDoc configuration directory named
themes/<theme>/(where<theme>is the the theme name set by the theme attribute). asciidoc(1) sets the themedir attribute to the theme directory path name. -
The theme attribute can also be set using the asciidoc(1)
--themeoption, the--themeoption can also be used to manage theme plugins. -
AsciiDoc ships with two themes: flask and volnitsky.
-
The
<theme>.cssfile replaces the defaultasciidoc.cssCSS file. -
The
<theme>.jsfile is included in addition to the defaultasciidoc.jsJavaScript file. -
If the data-uri attribute is defined then icons are loaded from the theme
iconssub-directory if it exists (i.e. the iconsdir attribute is set to themeiconssub-directory path). -
Embedded theme files are automatically inserted in the output files but you need to manually copy linked CSS and Javascript files to the location of the output documents.
-
Linked CSS and JavaScript theme files are linked to the same linked locations as other CSS and JavaScript files.
For example, the command-line option --theme foo (or --attribute
theme=foo) will cause asciidoc(1) to search configuration
file locations 1, 2 and 3 for a sub-directory called themes/foo
containing the stylesheet foo.css and optionally a JavaScript file
name foo.js.
An AsciiDoc document consists of a series of block elements starting with an optional document Header, followed by an optional Preamble, followed by zero or more document Sections.
Almost any combination of zero or more elements constitutes a valid AsciiDoc document: documents can range from a single sentence to a multi-part book.
Block elements consist of one or more lines of text and may contain other block elements.
The AsciiDoc block structure can be informally summarized as follows [1]:
Document ::= (Header?,Preamble?,Section*) Header ::= (Title,(AuthorInfo,RevisionInfo?)?) AuthorInfo ::= (FirstName,(MiddleName?,LastName)?,EmailAddress?) RevisionInfo ::= (RevisionNumber?,RevisionDate,RevisionRemark?) Preamble ::= (SectionBody) Section ::= (Title,SectionBody?,(Section)*) SectionBody ::= ((BlockTitle?,Block)|BlockMacro)+ Block ::= (Paragraph|DelimitedBlock|List|Table) List ::= (BulletedList|NumberedList|LabeledList|CalloutList) BulletedList ::= (ListItem)+ NumberedList ::= (ListItem)+ CalloutList ::= (ListItem)+ LabeledList ::= (ListEntry)+ ListEntry ::= (ListLabel,ListItem) ListLabel ::= (ListTerm+) ListItem ::= (ItemText,(List|ListParagraph|ListContinuation)*)
Where:
-
? implies zero or one occurrence, + implies one or more occurrences, * implies zero or more occurrences.
-
All block elements are separated by line boundaries.
-
BlockId,AttributeEntryandAttributeListblock elements (not shown) can occur almost anywhere. -
There are a number of document type and backend specific restrictions imposed on the block syntax.
-
The following elements cannot contain blank lines: Header, Title, Paragraph, ItemText.
-
A ListParagraph is a Paragraph with its listelement option set.
-
A ListContinuation is a list continuation element.
The Header contains document meta-data, typically title plus optional authorship and revision information:
-
The Header is optional, but if it is used it must start with a document title.
-
Optional Author and Revision information immediately follows the header title.
-
The document header must be separated from the remainder of the document by one or more blank lines and cannot contain blank lines.
-
The header can include comments.
-
The header can include attribute entries, typically doctype, lang, encoding, icons, data-uri, toc, numbered.
-
Header attributes are overridden by command-line attributes.
-
If the header contains non-UTF-8 characters then the encoding must precede the header (either in the document or on the command-line).
Here’s an example AsciiDoc document header:
Writing Documentation using AsciiDoc ==================================== Joe Bloggs <jbloggs@mymail.com> v2.0, February 2003: Rewritten for version 2 release.
The author information line contains the author’s name optionally followed by the author’s email address. The author’s name is formatted like:
firstname[ [middlename ]lastname][ <email>]]
i.e. a first name followed by optional middle and last names followed by an email address in that order. Multi-word first, middle and last names can be entered using the underscore as a word separator. The email address comes last and must be enclosed in angle <> brackets. Here a some examples of author information lines:
Joe Bloggs <jbloggs@mymail.com> Joe Bloggs Vincent Willem van_Gogh
If the author line does not match the above specification then the entire author line is treated as the first name.
The optional revision information line follows the author information line. The revision information can be one of two formats:
-
An optional document revision number followed by an optional revision date followed by an optional revision remark:
-
If the revision number is specified it must be followed by a comma.
-
The revision number must contain at least one numeric character.
-
Any non-numeric characters preceding the first numeric character will be dropped.
-
If a revision remark is specified it must be preceded by a colon. The revision remark extends from the colon up to the next blank line, attribute entry or comment and is subject to normal text substitutions.
-
If a revision number or remark has been set but the revision date has not been set then the revision date is set to the value of the docdate attribute.
Examples:
v2.0, February 2003 February 2003 v2.0, v2.0, February 2003: Rewritten for version 2 release. February 2003: Rewritten for version 2 release. v2.0,: Rewritten for version 2 release. :Rewritten for version 2 release.
-
-
The revision information line can also be an RCS/CVS/SVN
$Id$ marker:-
AsciiDoc extracts the revnumber, revdate, and author attributes from the
$Id$ revision marker and displays them in the document header. -
If an
$Id$ revision marker is used the header author line can be omitted.
Example:
$Id: mydoc.txt,v 1.5 2009/05/17 17:58:44 jbloggs Exp $
-
You can override or set header parameters by passing revnumber,
revremark, revdate, email, author, authorinitials,
firstname and lastname attributes using the asciidoc(1) -a
(--attribute) command-line option. For example:
$ asciidoc -a revdate=2004/07/27 article.txt
Attribute entries can also be added to the header for substitution in the header template with Attribute Entry elements.
The title element in HTML outputs is set to the AsciiDoc document title, you can set it to a different value by including a title attribute entry in the document header.
AsciiDoc has two mechanisms for optionally including additional meta-data in the header of the output document:
- docinfo configuration file sections
-
If a configuration file section named docinfo has been loaded then it will be included in the document header. Typically the docinfo section name will be prefixed with a + character so that it is appended to (rather than replace) other docinfo sections.
- docinfo files
-
Two docinfo files are recognized: one named
docinfoand a second named like the AsciiDoc source file with a-docinfosuffix. For example, if the source document is calledmydoc.txtthen the document information files would bedocinfo.xmlandmydoc-docinfo.xml(for DocBook outputs) anddocinfo.htmlandmydoc-docinfo.html(for HTML outputs). The docinfo, docinfo1 and docinfo2 attributes control which docinfo files are included in the output files.
The contents docinfo templates and files is dependent on the type of output:
- HTML
-
Valid head child elements. Typically style and script elements for CSS and JavaScript inclusion.
- DocBook
-
Valid articleinfo or bookinfo child elements. DocBook defines numerous elements for document meta-data, for example: copyrights, document history and authorship information. See the DocBook
./doc/article-docinfo.xmlexample that comes with the AsciiDoc distribution. The rendering of meta-data elements (or not) is DocBook processor dependent.
The Preamble is an optional untitled section body between the document Header and the first Section title.
In addition to the document title (level 0), AsciiDoc supports four section levels: 1 (top) to 4 (bottom). Section levels are delimited by section titles. Sections are translated using configuration file section markup templates. AsciiDoc generates the following intrinsic attributes specifically for use in section markup templates:
- level
-
The
levelattribute is the section level number, it is normally just the title level number (1..4). However, if theleveloffsetattribute is defined it will be added to thelevelattribute. Theleveloffsetattribute is useful for combining documents. - sectnum
-
The
-n(--section-numbers) command-line option generates thesectnum(section number) attribute. Thesectnumattribute is used for section numbers in HTML outputs (DocBook section numbering are handled automatically by the DocBook toolchain commands).
Section markup templates specify output markup and are defined in AsciiDoc configuration files. Section markup template names are derived as follows (in order of precedence):
-
From the title’s first positional attribute or template attribute. For example, the following three section titles are functionally equivalent:
[[terms]] [glossary] List of Terms ------------- ["glossary",id="terms"] List of Terms ------------- [template="glossary",id="terms"] List of Terms -------------
-
When the title text matches a configuration file
[specialsections]entry. -
If neither of the above the default
sect<level>template is used (where<level>is a number from 1 to 4).
In addition to the normal section template names (sect1, sect2, sect3, sect4) AsciiDoc has the following templates for frontmatter, backmatter and other special sections: abstract, preface, colophon, dedication, glossary, bibliography, synopsis, appendix, index. These special section templates generate the corresponding Docbook elements; for HTML outputs they default to the sect1 section template.
If no explicit section ID is specified an ID will be synthesised from the section title. The primary purpose of this feature is to ensure persistence of table of contents links (permalinks): the missing section IDs are generated dynamically by the JavaScript TOC generator after the page is loaded. If you link to a dynamically generated TOC address the page will load but the browser will ignore the (as yet ungenerated) section ID.
The IDs are generated by the following algorithm:
-
Replace all non-alphanumeric title characters with underscores.
-
Strip leading or trailing underscores.
-
Convert to lowercase.
-
Prepend the
idprefixattribute (so there’s no possibility of name clashes with existing document IDs). Prepend an underscore if theidprefixattribute is not defined. -
A numbered suffix (
_2,_3…) is added if a same named auto-generated section ID exists. -
If the
ascii-idsattribute is defined then non-ASCII characters are replaced with ASCII equivalents. This attribute should be should be avoided if possible as its sole purpose is to accommodate deficient downstream applications that cannot process non-ASCII ID attributes. If available, it will use the trans python module, otherwise it will fallback to using NFKD algorithm, which cannot handle all unicode characters. For example, Wstęp żółtej łąki will be translated to Wstep zoltej laki under trans and Wstep zotej aki under NFKD.
Example: the title Jim’s House would generate the ID _jim_s_house.
Section ID synthesis can be disabled by undefining the sectids
attribute.
AsciiDoc has a mechanism for mapping predefined section titles
auto-magically to specific markup templates. For example a title
Appendix A: Code Reference will automatically use the appendix
section markup template. The mappings from title to template
name are specified in [specialsections] sections in the Asciidoc
language configuration files (lang-*.conf). Section entries are
formatted like:
<title>=<template>
<title> is a Python regular expression and <template> is the name
of a configuration file markup template section. If the <title>
matches an AsciiDoc document section title then the backend output is
marked up using the <template> markup template (instead of the
default sect<level> section template). The {title} attribute value
is set to the value of the matched regular expression group named
title, if there is no title group {title} defaults to the whole
of the AsciiDoc section title. If <template> is blank then any
existing entry with the same <title> will be deleted.
AsciiDoc has two mechanisms for specifying non-default section markup templates: you can specify the template name explicitly (using the template attribute) or indirectly (using special section titles). Specifying a section template attribute explicitly is preferred. Auto-magical special section titles have the following drawbacks:
-
They are non-obvious, you have to know the exact matching title for each special section on a language by language basis.
-
Section titles are predefined and can only be customised with a configuration change.
-
The implementation is complicated by multiple languages: every special section title has to be defined for each language (in each of the
lang-*.conffiles).
Specifying special section template names explicitly does add more noise to the source document (the template attribute declaration), but the intention is obvious and the syntax is consistent with other AsciiDoc elements c.f. bibliographic, Q&A and glossary lists.
Special section titles have been deprecated but are retained for backward compatibility.
Inline document elements are used to format text and to perform various types of text substitution. Inline elements and inline element syntax is defined in the asciidoc(1) configuration files.
Here is a list of AsciiDoc inline elements in the (default) order in which they are processed:
- Special characters
-
These character sequences escape special characters used by the backend markup (typically
<,>, and&characters). See[specialcharacters]configuration file sections. - Quotes
-
Elements that markup words and phrases; usually for character formatting. See
[quotes]configuration file sections. - Special Words
-
Word or word phrase patterns singled out for markup without the need for further annotation. See
[specialwords]configuration file sections. - Replacements
-
Each replacement defines a word or word phrase pattern to search for along with corresponding replacement text. See
[replacements]configuration file sections. - Attribute references
-
Document attribute names enclosed in braces are replaced by the corresponding attribute value.
- Inline Macros
-
Inline macros are replaced by the contents of parametrized configuration file sections.
The AsciiDoc source document is read and processed as follows:
-
The document Header is parsed, header parameter values are substituted into the configuration file
[header]template section which is then written to the output file. -
Each document Section is processed and its constituent elements translated to the output file.
-
The configuration file
[footer]template section is substituted and written to the output file.
When a block element is encountered asciidoc(1) determines the type of block by checking in the following order (first to last): (section) Titles, BlockMacros, Lists, DelimitedBlocks, Tables, AttributeEntrys, AttributeLists, BlockTitles, Paragraphs.
The default paragraph definition [paradef-default] is last element
to be checked.
Knowing the parsing order will help you devise unambiguous macro, list and block syntax rules.
Inline substitutions within block elements are performed in the following default order:
-
Special characters
-
Quotes
-
Special words
-
Replacements
-
Attributes
-
Inline Macros
-
Replacements2
The substitutions and substitution order performed on Title, Paragraph and DelimitedBlock elements is determined by configuration file parameters.
Words and phrases can be formatted by enclosing inline text with quote characters:
- Emphasized text
-
Word phrases 'enclosed in single quote characters' (acute accents) or _underline characters_ are emphasized.
- Strong text
-
Word phrases *enclosed in asterisk characters* are rendered in a strong font (usually bold).
Monospaced text-
Word phrases +enclosed in plus characters+ are rendered in a monospaced font. Word phrases `enclosed in backtick characters` (grave accents) are also rendered in a monospaced font but in this case the enclosed text is rendered literally and is not subject to further expansion (see inline literal passthrough).
- ‘Single quoted text’
-
Phrases enclosed with a `single grave accent to the left and a single acute accent to the right' are rendered in single quotation marks.
- “Double quoted text”
-
Phrases enclosed with ``two grave accents to the left and two acute accents to the right'' are rendered in quotation marks.
- Unquoted text
-
Placing #hashes around text# does nothing, it is a mechanism to allow inline attributes to be applied to otherwise unformatted text.
New quote types can be defined by editing asciidoc(1) configuration files. See the Configuration Files section for details.
-
Quoting cannot be overlapped.
-
Different quoting types can be nested.
-
To suppress quoted text formatting place a backslash character immediately in front of the leading quote character(s). In the case of ambiguity between escaped and non-escaped text you will need to escape both leading and trailing quotes, in the case of multi-character quotes you may even need to escape individual characters.
Quoted text can be prefixed with an attribute list. The first positional attribute (role attribute) is translated by AsciiDoc to an HTML span element class attribute or a DocBook phrase element role attribute.
DocBook XSL Stylesheets translate DocBook phrase elements with role attributes to corresponding HTML span elements with the same class attributes; CSS can then be used to style the generated HTML. Thus CSS styling can be applied to both DocBook and AsciiDoc generated HTML outputs. You can also specify multiple class names separated by spaces.
CSS rules for text color, text background color, text size and text decorators are included in the distributed AsciiDoc CSS files and are used in conjunction with AsciiDoc xhtml11, html5 and docbook outputs. The CSS class names are:
-
<color> (text foreground color).
-
<color>-background (text background color).
-
big and small (text size).
-
underline, overline and line-through (strike through) text decorators.
Where <color> can be any of the sixteen HTML color names. Examples:
[red]#Obvious# and [big red yellow-background]*very obvious*.
[underline]#Underline text#, [overline]#overline text# and [blue line-through]*bold blue and line-through*.
is rendered as:
Obvious and very obvious.
Underline text, overline text and bold blue and line-through.
|
Note
|
Color and text decorator attributes are rendered for XHTML and HTML 5 outputs using CSS stylesheets. The mechanism to implement color and text decorator attributes is provided for DocBook toolchains via the DocBook phrase element role attribute, but the actual rendering is toolchain specific and is not part of the AsciiDoc distribution. |
There are actually two types of quotes:
Quoted must be bounded by white space or commonly adjoining punctuation characters. These are the most commonly used type of quote.
Unconstrained quotes have no boundary constraints and can be placed
anywhere within inline text. For consistency and to make them easier
to remember unconstrained quotes are double-ups of the _, *, +
and # constrained quotes:
__unconstrained emphasized text__ **unconstrained strong text** ++unconstrained monospaced text++ ##unconstrained unquoted text##
The following example emboldens the letter F:
**F**ile Open...
Put \^carets on either^ side of the text to be superscripted, put \~tildes on either side~ of text to be subscripted. For example, the following line:
e^πi^+1 = 0. H~2~O and x^10^. Some ^super text^ and ~some sub text~
Is rendered like:
eπi+1 = 0. H2O and x10. Some ^super text^ and ~some sub text~
Superscripts and subscripts are implemented as unconstrained quotes and they can be escaped with a leading backslash and prefixed with with an attribute list.
A plus character preceded by at least one space character at the end
of a non-blank line forces a line break. It generates a line break
(br) tag for HTML outputs and a custom XML asciidoc-br processing
instruction for DocBook outputs. The asciidoc-br processing
instruction is handled by a2x(1).
A line of three or more less-than (<<<) characters will generate a
hard page break in DocBook and printed HTML outputs. It uses the CSS
page-break-after property for HTML outputs and a custom XML
asciidoc-pagebreak processing instruction for DocBook outputs. The
asciidoc-pagebreak processing instruction is handled by
a2x(1). Hard page breaks are sometimes handy but as a general
rule you should let your page processor generate page breaks for you.
A line of three or more apostrophe characters will generate a ruler
line. It generates a ruler (hr) tag for HTML outputs and a custom
XML asciidoc-hr processing instruction for DocBook outputs. The
asciidoc-hr processing instruction is handled by a2x(1).
By default tab characters input files will translated to 8 spaces. Tab
expansion is set with the tabsize entry in the configuration file
[miscellaneous] section and can be overridden in included files by
setting a tabsize attribute in the include macro’s attribute list.
For example:
include::addendum.txt[tabsize=2]
The tab size can also be set using the attribute command-line option,
for example --attribute tabsize=4
The following replacements are defined in the default AsciiDoc configuration:
(C) copyright, (TM) trademark, (R) registered trademark, -- em dash, ... ellipsis, -> right arrow, <- left arrow, => right double arrow, <= left double arrow.
Which are rendered as:
© copyright, ™ trademark, ® registered trademark, — em dash, … ellipsis, → right arrow, ← left arrow, ⇒ right double arrow, ⇐ left double arrow.
You can also include arbitrary entity references in the AsciiDoc source. Examples:
➊ ¶
renders:
➊ ¶
To render a replacement literally escape it with a leading back-slash.
The Configuration Files section explains how to configure your own replacements.
Words defined in [specialwords] configuration file sections are
automatically marked up without having to be explicitly notated.
The Configuration Files section explains how to add and replace special words.
Document and section titles can be in either of two formats:
A two line title consists of a title line, starting hard against the left margin, and an underline. Section underlines consist a repeated character pairs spanning the width of the preceding title (give or take up to two characters):
The default title underlines for each of the document levels are:
Level 0 (top level): ====================== Level 1: ---------------------- Level 2: ~~~~~~~~~~~~~~~~~~~~~~ Level 3: ^^^^^^^^^^^^^^^^^^^^^^ Level 4 (bottom level): ++++++++++++++++++++++
Examples:
Level One Section Title -----------------------
Level 2 Subsection Title ~~~~~~~~~~~~~~~~~~~~~~~~
One line titles consist of a single line delimited on either side by one or more equals characters (the number of equals characters corresponds to the section level minus one). Here are some examples:
= Document Title (level 0) = == Section title (level 1) == === Section title (level 2) === ==== Section title (level 3) ==== ===== Section title (level 4) =====
|
Note
|
|
Setting the title’s first positional attribute or style attribute to float generates a free-floating title. A free-floating title is rendered just like a normal section title but is not formally associated with a text body and is not part of the regular section hierarchy so the normal ordering rules do not apply. Floating titles can also be used in contexts where section titles are illegal: for example sidebar and admonition blocks. Example:
[float] The second day ~~~~~~~~~~~~~~
Floating titles do not appear in a document’s table of contents.
A BlockTitle element is a single line beginning with a period followed by the title text. A BlockTitle is applied to the immediately following Paragraph, DelimitedBlock, List, Table or BlockMacro. For example:
.Notes - Note 1. - Note 2.
is rendered as:
-
Note 1.
-
Note 2.
A BlockId is a single line block element containing a unique identifier enclosed in double square brackets. It is used to assign an identifier to the ensuing block element. For example:
[[chapter-titles]] Chapter titles can be ...
The preceding example identifies the ensuing paragraph so it can be
referenced from other locations, for example with
<<chapter-titles,chapter titles>>.
BlockId elements can be applied to Title, Paragraph, List,
DelimitedBlock, Table and BlockMacro elements. The BlockId element
sets the {id} attribute for substitution in the subsequent block’s
markup template. If a second positional argument is supplied it sets
the {reftext} attribute which is used to set the DocBook xreflabel
attribute.
The BlockId element has the same syntax and serves the same function to the anchor inline macro.
An AttributeList block element is an attribute list on a line by itself:
-
AttributeList attributes are only applied to the immediately following block element — the attributes are made available to the block’s markup template.
-
Multiple contiguous AttributeList elements are additively combined in the order they appear.
-
The first positional attribute in the list is often used to specify the ensuing element’s style.
By default, only substitutions that take place inside attribute list values are attribute references, this is because not all attributes are destined to be marked up and rendered as text (for example the table cols attribute). To perform normal inline text substitutions (special characters, quotes, macros, replacements) on an attribute value you need to enclose it in single quotes. In the following quote block the second attribute value in the AttributeList is quoted to ensure the http macro is expanded to a hyperlink.
[quote,'https://en.wikipedia.org/wiki/Samuel_Johnson[Samuel Johnson]'] _____________________________________________________________________ Sir, a woman's preaching is like a dog's walking on his hind legs. It is not done well; but you are surprised to find it done at all. _____________________________________________________________________
Most block elements support the following attributes:
| Name | Backends | Description |
|---|---|---|
id |
html4, html5, xhtml11, docbook |
Unique identifier typically serve as link targets. Can also be set by the BlockId element. |
role |
html4, html5, xhtml11, docbook |
Role contains a string used to classify or subclassify an element and can be applied to AsciiDoc block elements. The AsciiDoc role attribute is translated to the role attribute in DocBook outputs and is included in the class attribute in HTML outputs, in this respect it behaves like the quoted text role attribute. DocBook XSL Stylesheets translate DocBook role attributes to HTML class attributes; CSS can then be used to style the generated HTML. |
reftext |
docbook |
reftext is used to set the DocBook xreflabel attribute. The reftext attribute can an also be set by the BlockId element. |
floatstyle |
docbook |
floatstyle is used to specify the floatstyle attribute for the titled table, example, image and equation blocks. This is useful when used in conjuction with the dblatex toolchain. A typical example would be to specify the value as floatstyle="[htbp]". |
Paragraphs are blocks of text terminated by a blank line, the end of file, or the start of a delimited block or a list. There are three paragraph syntaxes: normal, indented (literal) and admonition which are rendered, by default, with the corresponding paragraph style.
Each syntax has a default style, but you can explicitly apply any paragraph style to any paragraph syntax. You can also apply delimited block styles to single paragraphs.
The built-in paragraph styles are: normal, literal, verse, quote, listing, TIP, NOTE, IMPORTANT, WARNING, CAUTION, abstract, partintro, comment, example, sidebar, source, music, latex, graphviz.
Normal paragraph syntax consists of one or more non-blank lines of text. The first line must start hard against the left margin (no intervening white space). The default processing expectation is that of a normal paragraph of text.
Literal paragraphs are rendered verbatim in a monospaced font without any distinguishing background or border. By default there is no text formatting or substitutions within Literal paragraphs apart from Special Characters and Callouts.
The literal style is applied implicitly to indented paragraphs i.e. where the first line of the paragraph is indented by one or more space or tab characters. For example:
Consul *necessitatibus* per id, consetetur, eu pro everti postulant homero verear ea mea, qui.
Renders:
Consul *necessitatibus* per id, consetetur, eu pro everti postulant homero verear ea mea, qui.
|
Note
|
Because lists can be indented it’s possible for your indented paragraph to be misinterpreted as a list — in situations like this apply the literal style to a normal paragraph. |
Instead of using a paragraph indent you could apply the literal style explicitly, for example:
[literal] Consul *necessitatibus* per id, consetetur, eu pro everti postulant homero verear ea mea, qui.
Renders:
Consul *necessitatibus* per id, consetetur, eu pro everti postulant homero verear ea mea, qui.
The optional attribution and citetitle attributes (positional attributes 2 and 3) specify the author and source respectively.
The verse style retains the line breaks, for example:
[verse, William Blake, from Auguries of Innocence] To see a world in a grain of sand, And a heaven in a wild flower, Hold infinity in the palm of your hand, And eternity in an hour.
Which is rendered as:
To see a world in a grain of sand, And a heaven in a wild flower, Hold infinity in the palm of your hand, And eternity in an hour.
from Auguries of Innocence
The quote style flows the text at left and right margins, for example:
[quote, Bertrand Russell, The World of Mathematics (1956)] A good notation has subtlety and suggestiveness which at times makes it almost seem like a live teacher.
Which is rendered as:
A good notation has subtlety and suggestiveness which at times makes it almost seem like a live teacher.
The World of Mathematics (1956)
TIP, NOTE, IMPORTANT, WARNING and CAUTION admonishment
paragraph styles are generated by placing NOTE:, TIP:,
IMPORTANT:, WARNING: or CAUTION: as the first word of the
paragraph. For example:
NOTE: This is an example note.
Alternatively, you can specify the paragraph admonition style explicitly using an AttributeList element. For example:
[NOTE] This is an example note.
Renders:
|
Note
|
This is an example note. |
|
Tip
|
If your admonition requires more than a single paragraph use an admonition block instead. |
|
Note
|
Admonition customization with icons, iconsdir, icon and
caption attributes does not apply when generating DocBook output. If
you are going the DocBook route then the a2x(1) --no-icons
and --icons-dir options can be used to set the appropriate XSL
Stylesheets parameters.
|
By default the asciidoc(1) HTML backends generate text captions
instead of admonition icon image links. To generate links to icon
images define the icons attribute, for example using the -a
icons command-line option.
The iconsdir attribute sets the location of linked icon
images.
You can override the default icon image using the icon attribute to
specify the path of the linked image. For example:
[icon="./images/icons/wink.png"] NOTE: What lovely war.
Use the caption attribute to customize the admonition captions (not
applicable to docbook backend). The following example suppresses the
icon image and customizes the caption of a NOTE admonition
(undefining the icons attribute with icons=None is only necessary
if admonition icons have been enabled):
[icons=None, caption="My Special Note"] NOTE: This is my special note.
This subsection also applies to Admonition Blocks.
Delimited blocks are blocks of text enveloped by leading and trailing
delimiter lines (normally a series of four or more repeated
characters). The behavior of Delimited Blocks is specified by entries
in configuration file [blockdef-*] sections.
AsciiDoc ships with a number of predefined DelimitedBlocks (see the
asciidoc.conf configuration file in the asciidoc(1) program
directory):
Predefined delimited block underlines:
CommentBlock: ////////////////////////// PassthroughBlock: ++++++++++++++++++++++++++ ListingBlock: -------------------------- LiteralBlock: .......................... SidebarBlock: ************************** QuoteBlock: __________________________ ExampleBlock: ========================== OpenBlock: --
| Attributes | Callouts | Macros | Quotes | Replacements | Special chars | Special words | |
|---|---|---|---|---|---|---|---|
PassthroughBlock |
Yes |
No |
Yes |
No |
No |
No |
No |
ListingBlock |
No |
Yes |
No |
No |
No |
Yes |
No |
LiteralBlock |
No |
Yes |
No |
No |
No |
Yes |
No |
SidebarBlock |
Yes |
No |
Yes |
Yes |
Yes |
Yes |
Yes |
QuoteBlock |
Yes |
No |
Yes |
Yes |
Yes |
Yes |
Yes |
ExampleBlock |
Yes |
No |
Yes |
Yes |
Yes |
Yes |
Yes |
OpenBlock |
Yes |
No |
Yes |
Yes |
Yes |
Yes |
Yes |
ListingBlocks are rendered verbatim in a monospaced font, they retain line and whitespace formatting and are often distinguished by a background or border. There is no text formatting or substitutions within Listing blocks apart from Special Characters and Callouts. Listing blocks are often used for computer output and file listings.
Here’s an example:
--------------------------------------
#include <stdio.h>
int main() {
printf("Hello World!\n");
exit(0);
}
--------------------------------------
Which will be rendered like:
#include <stdio.h>
int main() {
printf("Hello World!\n");
exit(0);
}
By convention filter blocks use the listing block syntax and are implemented as distinct listing block styles.
LiteralBlocks are rendered just like literal paragraphs. Example:
................................... Consul *necessitatibus* per id, consetetur, eu pro everti postulant homero verear ea mea, qui. ...................................
Renders:
Consul *necessitatibus* per id, consetetur, eu pro everti postulant homero verear ea mea, qui.
If the listing style is applied to a LiteralBlock it will be rendered as a ListingBlock (this is handy if you have a listing containing a ListingBlock).
A sidebar is a short piece of text presented outside the narrative flow of the main text. The sidebar is normally presented inside a bordered box to set it apart from the main text.
The sidebar body is treated like a normal section body.
Here’s an example:
.An Example Sidebar ************************************************ Any AsciiDoc SectionBody element (apart from SidebarBlocks) can be placed inside a sidebar. ************************************************
Which will be rendered like:
Any AsciiDoc SectionBody element (apart from SidebarBlocks) can be placed inside a sidebar.
The contents of CommentBlocks are not processed; they are useful for annotations and for excluding new or outdated content that you don’t want displayed. CommentBlocks are never written to output files. Example:
////////////////////////////////////////// CommentBlock contents are not processed by asciidoc(1). //////////////////////////////////////////
See also Comment Lines.
|
Note
|
System macros are executed inside comment blocks. |
By default the block contents is subject only to attributes and macros substitutions (use an explicit subs attribute to apply different substitutions). PassthroughBlock content will often be backend specific. Here’s an example:
[subs="quotes"] ++++++++++++++++++++++++++++++++++++++ <table border="1"><tr> <td>*Cell 1*</td> <td>*Cell 2*</td> </tr></table> ++++++++++++++++++++++++++++++++++++++
The following styles can be applied to passthrough blocks:
- pass
-
No substitutions are performed. This is equivalent to
subs="none". - asciimath, latexmath
-
By default no substitutions are performed, the contents are rendered as mathematical formulas.
QuoteBlocks are used for quoted passages of text. There are two styles: quote and verse. The style behavior is identical to quote and verse paragraphs except that blocks can contain multiple paragraphs and, in the case of the quote style, other section elements. The first positional attribute sets the style, if no attributes are specified the quote style is used. The optional attribution and citetitle attributes (positional attributes 2 and 3) specify the quote’s author and source. For example:
[quote, Sir Arthur Conan Doyle, The Adventures of Sherlock Holmes] ____________________________________________________________________ As he spoke there was the sharp sound of horses' hoofs and grating wheels against the curb, followed by a sharp pull at the bell. Holmes whistled. "A pair, by the sound," said he. "Yes," he continued, glancing out of the window. "A nice little brougham and a pair of beauties. A hundred and fifty guineas apiece. There's money in this case, Watson, if there is nothing else." ____________________________________________________________________
Which is rendered as:
As he spoke there was the sharp sound of horses' hoofs and grating wheels against the curb, followed by a sharp pull at the bell. Holmes whistled.
"A pair, by the sound," said he. "Yes," he continued, glancing out of the window. "A nice little brougham and a pair of beauties. A hundred and fifty guineas apiece. There’s money in this case, Watson, if there is nothing else."
The Adventures of Sherlock Holmes
ExampleBlocks encapsulate the DocBook Example element and are used for, well, examples. Example blocks can be titled by preceding them with a BlockTitle. DocBook toolchains will normally automatically number examples and generate a List of Examples backmatter section.
Example blocks are delimited by lines of equals characters and can contain any block elements apart from Titles, BlockTitles and Sidebars) inside an example block. For example:
.An example ===================================================================== Qui in magna commodo, est labitur dolorum an. Est ne magna primis adolescens. =====================================================================
Renders:
Qui in magna commodo, est labitur dolorum an. Est ne magna primis adolescens.
A title prefix that can be inserted with the caption attribute
(HTML backends). For example:
[caption="Example 1: "] .An example with a custom caption ===================================================================== Qui in magna commodo, est labitur dolorum an. Est ne magna primis adolescens. =====================================================================
The ExampleBlock definition includes a set of admonition styles (NOTE, TIP, IMPORTANT, WARNING, CAUTION) for generating admonition blocks (admonitions containing more than a single paragraph). Just precede the ExampleBlock with an attribute list specifying the admonition style name. For example:
[NOTE] .A NOTE admonition block ===================================================================== Qui in magna commodo, est labitur dolorum an. Est ne magna primis adolescens. . Fusce euismod commodo velit. . Vivamus fringilla mi eu lacus. .. Fusce euismod commodo velit. .. Vivamus fringilla mi eu lacus. . Donec eget arcu bibendum nunc consequat lobortis. =====================================================================
Renders:
|
Note
|
A NOTE admonition block
Qui in magna commodo, est labitur dolorum an. Est ne magna primis adolescens.
|
See also Admonition Icons and Captions.
Open blocks are special:
-
The open block delimiter is line containing two hyphen characters (instead of four or more repeated characters).
-
They can be used to group block elements for List item continuation.
-
Open blocks can be styled to behave like any other type of delimited block. The following built-in styles can be applied to open blocks: literal, verse, quote, listing, TIP, NOTE, IMPORTANT, WARNING, CAUTION, abstract, partintro, comment, example, sidebar, source, music, latex, graphviz. For example, the following open block and listing block are functionally identical:
[listing] -- Lorum ipsum ... --
--------------- Lorum ipsum ... ---------------
-
An unstyled open block groups section elements but otherwise does nothing.
Open blocks are used to generate document abstracts and book part introductions:
-
Apply the abstract style to generate an abstract, for example:
[abstract] -- In this paper we will ... --
-
Apply the partintro style to generate a book part introduction for a multi-part book, for example:
[partintro] .Optional part introduction title -- Optional part introduction goes here. --
-
-
Bulleted lists. Also known as itemized or unordered lists.
-
Numbered lists. Also called ordered lists.
-
Labeled lists. Sometimes called variable or definition lists.
-
Callout lists (a list of callout annotations).
-
List item indentation is optional and does not determine nesting, indentation does however make the source more readable.
-
Another list or a literal paragraph immediately following a list item will be implicitly included in the list item; use list item continuation to explicitly append other block elements to a list item.
-
A comment block or a comment line block macro element will terminate a list — use inline comment lines to put comments inside lists.
-
The
listindexintrinsic attribute is the current list item index (1..). If this attribute is used outside a list then it’s value is the number of items in the most recently closed list. Useful for displaying the number of items in a list.
Bulleted list items start with a single dash or one to five asterisks followed by some white space then some text. Bulleted list syntaxes are:
- List item. * List item. ** List item. *** List item. **** List item. ***** List item.
List item numbers are explicit or implicit.
List items begin with a number followed by some white space then the item text. The numbers can be decimal (arabic), roman (upper or lower case) or alpha (upper or lower case). Decimal and alpha numbers are terminated with a period, roman numbers are terminated with a closing parenthesis. The different terminators are necessary to ensure i, v and x roman numbers are are distinguishable from x, v and x alpha numbers. Examples:
1. Arabic (decimal) numbered list item. a. Lower case alpha (letter) numbered list item. F. Upper case alpha (letter) numbered list item. iii) Lower case roman numbered list item. IX) Upper case roman numbered list item.
List items begin one to five period characters, followed by some white space then the item text. Examples:
. Arabic (decimal) numbered list item. .. Lower case alpha (letter) numbered list item. ... Lower case roman numbered list item. .... Upper case alpha (letter) numbered list item. ..... Upper case roman numbered list item.
You can use the style attribute (also the first positional attribute) to specify an alternative numbering style. The numbered list style can be one of the following values: arabic, loweralpha, upperalpha, lowerroman, upperroman.
Here are some examples of bulleted and numbered lists:
- Praesent eget purus quis magna eleifend eleifend.
1. Fusce euismod commodo velit.
a. Fusce euismod commodo velit.
b. Vivamus fringilla mi eu lacus.
c. Donec eget arcu bibendum nunc consequat lobortis.
2. Vivamus fringilla mi eu lacus.
i) Fusce euismod commodo velit.
ii) Vivamus fringilla mi eu lacus.
3. Donec eget arcu bibendum nunc consequat lobortis.
4. Nam fermentum mattis ante.
- Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
* Fusce euismod commodo velit.
** Qui in magna commodo, est labitur dolorum an. Est ne magna primis
adolescens. Sit munere ponderum dignissim et. Minim luptatum et
vel.
** Vivamus fringilla mi eu lacus.
* Donec eget arcu bibendum nunc consequat lobortis.
- Nulla porttitor vulputate libero.
. Fusce euismod commodo velit.
. Vivamus fringilla mi eu lacus.
[upperroman]
.. Fusce euismod commodo velit.
.. Vivamus fringilla mi eu lacus.
. Donec eget arcu bibendum nunc consequat lobortis.
Which render as:
-
Praesent eget purus quis magna eleifend eleifend.
-
Fusce euismod commodo velit.
-
Fusce euismod commodo velit.
-
Vivamus fringilla mi eu lacus.
-
Donec eget arcu bibendum nunc consequat lobortis.
-
-
Vivamus fringilla mi eu lacus.
-
Fusce euismod commodo velit.
-
Vivamus fringilla mi eu lacus.
-
-
Donec eget arcu bibendum nunc consequat lobortis.
-
Nam fermentum mattis ante.
-
-
Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
-
Fusce euismod commodo velit.
-
Qui in magna commodo, est labitur dolorum an. Est ne magna primis adolescens. Sit munere ponderum dignissim et. Minim luptatum et vel.
-
Vivamus fringilla mi eu lacus.
-
-
Donec eget arcu bibendum nunc consequat lobortis.
-
-
Nulla porttitor vulputate libero.
-
Fusce euismod commodo velit.
-
Vivamus fringilla mi eu lacus.
-
Fusce euismod commodo velit.
-
Vivamus fringilla mi eu lacus.
-
-
Donec eget arcu bibendum nunc consequat lobortis.
-
A predefined compact option is available to bulleted and numbered lists — this translates to the DocBook spacing="compact" lists attribute which may or may not be processed by the DocBook toolchain. Example:
[options="compact"] - Compact list item. - Another compact list item.
|
Tip
|
To apply the compact option globally define a document-wide
compact-option attribute, e.g. using the -a compact-option
command-line option.
|
You can set the list start number using the start attribute (works for HTML outputs and DocBook outputs processed by DocBook XSL Stylesheets). Example:
[start=7] . List item 7. . List item 8.
Labeled list items consist of one or more text labels followed by the text of the list item.
An item label begins a line with an alphanumeric character hard against the left margin and ends with two, three or four colons or two semi-colons. A list item can have multiple labels, one per line.
The list item text consists of one or more lines of text starting after the last label (either on the same line or a new line) and can be followed by nested List or ListParagraph elements. Item text can be optionally indented.
Here are some examples:
In::
Lorem::
Fusce euismod commodo velit.
Fusce euismod commodo velit.
Ipsum:: Vivamus fringilla mi eu lacus.
* Vivamus fringilla mi eu lacus.
* Donec eget arcu bibendum nunc consequat lobortis.
Dolor::
Donec eget arcu bibendum nunc consequat lobortis.
Suspendisse;;
A massa id sem aliquam auctor.
Morbi;;
Pretium nulla vel lorem.
In;;
Dictum mauris in urna.
Vivamus::: Fringilla mi eu lacus.
Donec::: Eget arcu bibendum nunc consequat lobortis.
Which render as:
- In
- Lorem
-
Fusce euismod commodo velit.
Fusce euismod commodo velit.
- Ipsum
-
Vivamus fringilla mi eu lacus.
-
Vivamus fringilla mi eu lacus.
-
Donec eget arcu bibendum nunc consequat lobortis.
-
- Dolor
-
Donec eget arcu bibendum nunc consequat lobortis.
- Suspendisse
-
A massa id sem aliquam auctor.
- Morbi
-
Pretium nulla vel lorem.
- In
-
Dictum mauris in urna.
- Vivamus
-
Fringilla mi eu lacus.
- Donec
-
Eget arcu bibendum nunc consequat lobortis.
The horizontal labeled list style (also the first positional attribute) places the list text side-by-side with the label instead of under the label. Here is an example:
[horizontal] *Lorem*:: Fusce euismod commodo velit. Qui in magna commodo, est labitur dolorum an. Est ne magna primis adolescens. Fusce euismod commodo velit. *Ipsum*:: Vivamus fringilla mi eu lacus. - Vivamus fringilla mi eu lacus. - Donec eget arcu bibendum nunc consequat lobortis. *Dolor*:: - Vivamus fringilla mi eu lacus. - Donec eget arcu bibendum nunc consequat lobortis.
Which render as:
| Lorem |
Fusce euismod commodo velit. Qui in magna commodo, est labitur dolorum an. Est ne magna primis adolescens. Fusce euismod commodo velit. |
| Ipsum |
Vivamus fringilla mi eu lacus.
|
| Dolor |
|
|
Note
|
|
AsciiDoc comes pre-configured with a qanda style labeled list for generating DocBook question and answer (Q&A) lists. Example:
[qanda]
Question one::
Answer one.
Question two::
Answer two.
Renders:
-
Question one
Answer one.
-
Question two
Answer two.
AsciiDoc comes pre-configured with a glossary style labeled list for generating DocBook glossary lists. Example:
[glossary]
A glossary term::
The corresponding definition.
A second glossary term::
The corresponding definition.
For working examples see the article.txt and book.txt documents in
the AsciiDoc ./doc distribution directory.
|
Note
|
To generate valid DocBook output glossary lists must be located in a section that uses the glossary section markup template. |
AsciiDoc comes with a predefined bibliography bulleted list style generating DocBook bibliography entries. Example:
[bibliography] .Optional list title - [[[taoup]]] Eric Steven Raymond. 'The Art of UNIX Programming'. Addison-Wesley. ISBN 0-13-142901-9. - [[[walsh-muellner]]] Norman Walsh & Leonard Muellner. 'DocBook - The Definitive Guide'. O'Reilly & Associates. 1999. ISBN 1-56592-580-7.
The [[[<reference>]]] syntax is a bibliography entry anchor, it
generates an anchor named <reference> and additionally displays
[<reference>] at the anchor position. For example [[[taoup]]]
generates an anchor named taoup that displays [taoup] at the
anchor position. Cite the reference from elsewhere your document using
<<taoup>>, this displays a hyperlink ([taoup]) to the
corresponding bibliography entry anchor.
For working examples see the article.txt and book.txt documents in
the AsciiDoc ./doc distribution directory.
|
Note
|
To generate valid DocBook output bibliography lists must be located in a bibliography section. |
Another list or a literal paragraph immediately following a list item is implicitly appended to the list item; to append other block elements to a list item you need to explicitly join them to the list item with a list continuation (a separator line containing a single plus character). Multiple block elements can be appended to a list item using list continuations (provided they are legal list item children in the backend markup).
Here are some examples of list item continuations: list item one contains multiple continuations; list item two is continued with an OpenBlock containing multiple elements:
1. List item one. + List item one continued with a second paragraph followed by an Indented block. + ................. $ ls *.sh $ mv *.sh ~/tmp ................. + List item continued with a third paragraph. 2. List item two continued with an open block. + -- This paragraph is part of the preceding list item. a. This list is nested and does not require explicit item continuation. + This paragraph is part of the preceding list item. b. List item b. This paragraph belongs to item two of the outer list. --
Renders:
-
List item one.
List item one continued with a second paragraph followed by an Indented block.
$ ls *.sh $ mv *.sh ~/tmp
List item continued with a third paragraph.
-
List item two continued with an open block.
This paragraph is part of the preceding list item.
-
This list is nested and does not require explicit item continuation.
This paragraph is part of the preceding list item.
-
List item b.
This paragraph belongs to item two of the outer list.
-
The shipped AsciiDoc configuration includes three footnote inline macros:
footnote:[<text>]-
Generates a footnote with text
<text>. footnoteref:[<id>,<text>]-
Generates a footnote with a reference ID
<id>and text<text>. footnoteref:[<id>]-
Generates a reference to the footnote with ID
<id>.
The footnote text can span multiple lines.
The xhtml11 and html5 backends render footnotes dynamically using JavaScript; html4 outputs do not use JavaScript and leave the footnotes inline; docbook footnotes are processed by the downstream DocBook toolchain.
Example footnotes:
A footnote footnote:[An example footnote.]; a second footnote with a reference ID footnoteref:[note2,Second footnote.]; finally a reference to the second footnote footnoteref:[note2].
Renders:
The shipped AsciiDoc configuration includes the inline macros for generating DocBook index entries.
indexterm:[<primary>,<secondary>,<tertiary>](((<primary>,<secondary>,<tertiary>)))-
This inline macro generates an index term (the
<secondary>and<tertiary>positional attributes are optional). Example:indexterm:[Tigers,Big cats](or, using the alternative syntax(((Tigers,Big cats))). Index terms that have secondary and tertiary entries also generate separate index terms for the secondary and tertiary entries. The index terms appear in the index, not the primary text flow. indexterm2:[<primary>]((<primary>))-
This inline macro generates an index term that appears in both the index and the primary text flow. The
<primary>should not be padded to the left or right with white space characters.
For working examples see the article.txt and book.txt documents in
the AsciiDoc ./doc distribution directory.
|
Note
|
Index entries only really make sense if you are generating DocBook markup — DocBook conversion programs automatically generate an index at the point an Index section appears in source document. |
Callouts are a mechanism for annotating verbatim text (for example: source code, computer output and user input). Callout markers are placed inside the annotated text while the actual annotations are presented in a callout list after the annotated text. Here’s an example:
.MS-DOS directory listing ----------------------------------------------------- 10/17/97 9:04 <DIR> bin 10/16/97 14:11 <DIR> DOS <1> 10/16/97 14:40 <DIR> Program Files 10/16/97 14:46 <DIR> TEMP 10/17/97 9:04 <DIR> tmp 10/16/97 14:37 <DIR> WINNT 10/16/97 14:25 119 AUTOEXEC.BAT <2> 2/13/94 6:21 54,619 COMMAND.COM <2> 10/16/97 14:25 115 CONFIG.SYS <2> 11/16/97 17:17 61,865,984 pagefile.sys 2/13/94 6:21 9,349 WINA20.386 <3> ----------------------------------------------------- \<1> This directory holds MS-DOS. \<2> System startup code for DOS. \<3> Some sort of Windows 3.1 hack.
Which renders:
10/17/97 9:04 <DIR> bin 10/16/97 14:11 <DIR> DOS (1) 10/16/97 14:40 <DIR> Program Files 10/16/97 14:46 <DIR> TEMP 10/17/97 9:04 <DIR> tmp 10/16/97 14:37 <DIR> WINNT 10/16/97 14:25 119 AUTOEXEC.BAT (2) 2/13/94 6:21 54,619 COMMAND.COM (2) 10/16/97 14:25 115 CONFIG.SYS (2) 11/16/97 17:17 61,865,984 pagefile.sys 2/13/94 6:21 9,349 WINA20.386 (3)
-
This directory holds MS-DOS.
-
System startup code for DOS.
-
Some sort of Windows 3.1 hack.
-
The callout marks are whole numbers enclosed in angle brackets — they refer to the correspondingly numbered item in the following callout list.
-
By default callout marks are confined to LiteralParagraphs, LiteralBlocks and ListingBlocks (although this is a configuration file option and can be changed).
-
Callout list item numbering is fairly relaxed — list items can start with
<n>,n>or>wherenis the optional list item number (in the latter case list items starting with a single>character are implicitly numbered starting at one). -
Callout lists should not be nested.
-
Callout lists cannot be used within tables.
-
Callout lists start list items hard against the left margin.
-
If you want to present a number inside angle brackets you’ll need to escape it with a backslash to prevent it being interpreted as a callout mark.
|
Note
|
Define the AsciiDoc icons attribute (for example using the -a
icons command-line option) to display callout icons.
|
Callout marks are generated by the callout inline macro while callout lists are generated using the callout list definition. The callout macro and callout list are special in that they work together. The callout inline macro is not enabled by the normal macros substitutions option, instead it has its own callouts substitution option.
The following attributes are available during inline callout macro substitution:
{index}-
The callout list item index inside the angle brackets.
{coid}-
An identifier formatted like
CO<listnumber>-<index>that uniquely identifies the callout mark. For exampleCO2-4identifies the fourth callout mark in the second set of callout marks.
The {coids} attribute can be used during callout list item
substitution — it is a space delimited list of callout IDs that refer
to the explanatory list item.
You can annotate working code examples with callouts — just remember
to put the callouts inside source code comments. This example displays
the test.py source file (containing a single callout) using the
source (code highlighter) filter:
[source,python] ------------------------------------------- \include::test.py[] ------------------------------------------- \<1> Print statement.
test.py sourceprint 'Hello World!' # <1>
Macros are a mechanism for substituting parametrized text into output documents.
Macros have a name, a single target argument and an attribute
list. The usual syntax is <name>:<target>[<attrlist>] (for
inline macros) and <name>::<target>[<attrlist>] (for block
macros). Here are some examples:
https://docbook.org/[DocBook.org] include::chapt1.txt[tabsize=2] mailto:srackham@gmail.com[]
-
<name>is the macro name. It can only contain letters, digits or dash characters and cannot start with a dash. -
The optional
<target>cannot contain white space characters. -
<attrlist>is a list of attributes enclosed in square brackets. -
]characters inside attribute lists must be escaped with a backslash. -
Expansion of macro references can normally be escaped by prefixing a backslash character (see the AsciiDoc FAQ for examples of exceptions to this rule).
-
Attribute references in block macros are expanded.
-
The substitutions performed prior to Inline macro macro expansion are determined by the inline context.
-
Macros are processed in the order they appear in the configuration file(s).
-
Calls to inline macros can be nested inside different inline macros (an inline macro call cannot contain a nested call to itself).
-
In addition to
<name>,<target>and<attrlist>the<passtext>and<subslist>named groups are available to passthrough macros. A macro is a passthrough macro if the definition includes a<passtext>named group.
Inline Macros occur in an inline element context. Predefined Inline macros include URLs, image and link macros.
http, https, ftp, file, mailto and callto URLs are rendered using predefined inline macros.
-
If you don’t need a custom link caption you can enter the http, https, ftp, file URLs and email addresses without any special macro syntax.
-
If the
<attrlist>is empty the URL is displayed.
Here are some examples:
https://docbook.org/[DocBook.org] https://docbook.org/ mailto:joe.bloggs@foobar.com[email Joe Bloggs] joe.bloggs@foobar.com
Which are rendered:
If the <target> necessitates space characters use %20, for example
large%20image.png.
Two AsciiDoc inline macros are provided for creating hypertext links within an AsciiDoc document. You can use either the standard macro syntax or the (preferred) alternative.
Used to specify hypertext link targets:
[[<id>,<xreflabel>]] anchor:<id>[<xreflabel>]
The <id> is a unique string that conforms to the output markup’s
anchor syntax. The optional <xreflabel> is the text to be displayed
by captionless xref macros that refer to this anchor. The optional
<xreflabel> is only really useful when generating DocBook output.
Example anchor:
[[X1]]
You may have noticed that the syntax of this inline element is the same as that of the BlockId block element, this is no coincidence since they are functionally equivalent.
Creates a hypertext link to a document anchor.
<<<id>,<caption>>> xref:<id>[<caption>]
The <id> refers to an anchor ID. The optional <caption> is the
link’s displayed text. Example:
<<X21,attribute lists>>
If <caption> is not specified then the displayed text is
auto-generated:
-
The AsciiDoc xhtml11 and html5 backends display the
<id>enclosed in square brackets. -
If DocBook is produced the DocBook toolchain is responsible for the displayed text which will normally be the referenced figure, table or section title number followed by the element’s title text.
Here is an example:
[[tiger_image]] .Tyger tyger image::tiger.png[] This can be seen in <<tiger_image>>.
Hypertext links to files on the local file system are specified using the link inline macro.
link:<target>[<caption>]
The link macro generates relative URLs. The link macro <target> is
the target file name (relative to the file system location of the
referring document). The optional <caption> is the link’s displayed
text. If <caption> is not specified then <target> is displayed.
Example:
link:downloads/foo.zip[download foo.zip]
You can use the <filename>#<id> syntax to refer to an anchor within
a target document but this usually only makes sense when targeting
HTML documents.
Inline images are inserted into the output document using the image macro. The inline syntax is:
image:<target>[<attributes>]
The contents of the image file <target> is displayed. To display the
image its file format must be supported by the target backend
application. HTML and DocBook applications normally support PNG or JPG
files.
<target> file name paths are relative to the location of the
referring document.
-
The optional alt attribute is also the first positional attribute, it specifies alternative text which is displayed if the output application is unable to display the image file (see also Use of ALT texts in IMGs). For example:
image:images/logo.png[Company Logo]
-
The optional title attribute provides a title for the image. The block image macro renders the title alongside the image. The inline image macro displays the title as a popup “tooltip” in visual browsers (AsciiDoc HTML outputs only).
-
The optional
widthandheightattributes scale the image size and can be used in any combination. The units are pixels. The following example scales the previous example to a height of 32 pixels:image:images/logo.png["Company Logo",height=32]
-
The optional
linkattribute is used to link the image to an external document. The following example links a screenshot thumbnail to a full size version:image:screen-thumbnail.png[height=32,link="screen.png"]
-
The optional
scaledwidthattribute is only used in DocBook block images (specifically for PDF documents). The following example scales the images to 75% of the available print width:image::images/logo.png[scaledwidth="75%",alt="Company Logo"]
-
The image
scaleattribute sets the DocBookimagedataelementscaleattribute. -
The optional
alignattribute aligns block macro images horizontally. Allowed values arecenter,leftandright. For example:image::images/tiger.png["Tiger image",align="left"]
-
The optional
floatattribute floats the imageleftorrighton the page (works with HTML outputs only, has no effect on DocBook outputs).floatandalignattributes are mutually exclusive. Use theunfloat::[]block macro to stop floating.
See comment block macro.
A Block macro reference must be contained in a single line separated either side by a blank line or a block delimiter.
Block macros behave just like Inline macros, with the following differences:
-
They occur in a block context.
-
The default syntax is
<name>::<target>[<attrlist>](two colons, not one). -
Markup template section names end in
-blockmacroinstead of-inlinemacro.
The Block Identifier macro sets the id attribute and has the same
syntax as the anchor inline macro since it performs
essentially the same function — block templates use the id
attribute as a block element ID. For example:
[[X30]]
This is equivalent to the [id="X30"] AttributeList element).
The image block macro is used to display images in a block context. The syntax is:
image::<target>[<attributes>]
The block image macro has the same macro attributes as it’s
inline image macro counterpart.
|
Warning
|
Unlike the inline image macro, the entire block image macro
must be on a single line.
|
Block images can be titled by preceding the image macro with a BlockTitle. DocBook toolchains normally number titled block images and optionally list them in an automatically generated List of Figures backmatter section.
This example:
.Main circuit board image::images/layout.png[J14P main circuit board]
is equivalent to:
image::images/layout.png["J14P main circuit board", title="Main circuit board"]
A title prefix that can be inserted with the caption attribute
(HTML backends). For example:
.Main circuit board [caption="Figure 2: "] image::images/layout.png[J14P main circuit board]
If you define the data-uri attribute then images will be embedded in
XHTML outputs using the
data URI scheme. You
can use the data-uri attribute with the xhtml11 and html5
backends to produce single-file XHTML documents with embedded images
and CSS, for example:
$ asciidoc -a data-uri mydocument.txt
|
Note
|
|
Single lines starting with two forward slashes hard up against the left margin are treated as comments. Comment lines do not appear in the output unless the showcomments attribute is defined. Comment lines have been implemented as both block and inline macros so a comment line can appear as a stand-alone block or within block elements that support inline macro expansion. Example comment line:
// This is a comment.
If the showcomments attribute is defined comment lines are written to the output:
-
In DocBook the comment lines are enclosed by the remark element (which may or may not be rendered by your toolchain).
-
The showcomments attribute does not expose Comment Blocks. Comment Blocks are never passed to the output.
System macros are block macros that perform a predefined task and are hardwired into the asciidoc(1) program.
-
You can escape system macros with a leading backslash character (as you can with other macros).
-
The syntax and tasks performed by system macros is built into asciidoc(1) so they don’t appear in configuration files. You can however customize the syntax by adding entries to a configuration file
[macros]section.
The include and include1 system macros to include the contents of
a named file into the source document.
The include macro includes a file as if it were part of the parent
document — tabs are expanded and system macros processed. The
contents of include1 files are not subject to tab expansion or
system macro processing nor are attribute or lower priority
substitutions performed. The include1 macro’s intended use is to
include verbatim embedded CSS or scripts into configuration file
headers. Example:
include::chapter1.txt[tabsize=4]
-
If the included file name is specified with a relative path then the path is relative to the location of the referring document.
-
Include macros can appear inside configuration files.
-
Files included from within DelimitedBlocks are read to completion to avoid false end-of-block underline termination.
-
Attribute references are expanded inside the include target; if an attribute is undefined then the included file is silently skipped.
-
The tabsize macro attribute sets the number of space characters to be used for tab expansion in the included file (not applicable to
include1macro). -
The depth macro attribute sets the maximum permitted number of subsequent nested includes (not applicable to
include1macro which does not process nested includes). Setting depth to 1 disables nesting inside the included file. By default, nesting is limited to a depth of ten. -
The
linesmacro attribute can be used to include specific lines of the file. You can specify a range of pages by using..between the two numbers, for example1..10would include the first 10 lines. You can include multiple ranges or invdividual pages by using a comma or semi-colon, for example1..10,45,50..60. -
If the warnings attribute is set to False (or any other Python literal that evaluates to boolean false) then no warning message is printed if the included file does not exist. By default warnings are enabled.
-
Internally the
include1macro is translated to theinclude1system attribute which means it must be evaluated in a region where attribute substitution is enabled. To inhibit nested substitution in included files it is preferable to use theincludemacro and set the attributedepth=1.
Lines of text in the source document can be selectively included or excluded from processing based on the existence (or not) of a document attribute.
Document text between the ifdef and endif macros is included if a
document attribute is defined:
ifdef::<attribute>[] : endif::<attribute>[]
Document text between the ifndef and endif macros is not included
if a document attribute is defined:
ifndef::<attribute>[] : endif::<attribute>[]
<attribute> is an attribute name which is optional in the trailing
endif macro.
If you only want to process a single line of text then the text can be
put inside the square brackets and the endif macro omitted, for
example:
ifdef::revnumber[Version number 42]
Is equivalent to:
ifdef::revnumber[] Version number 42 endif::revnumber[]
ifdef and ifndef macros also accept multiple attribute names:
-
Multiple , separated attribute names evaluate to defined if one or more of the attributes is defined, otherwise it’s value is undefined.
-
Multiple + separated attribute names evaluate to defined if all of the attributes is defined, otherwise it’s value is undefined.
Document text between the ifeval and endif macros is included if
the Python expression inside the square brackets is true. Example:
ifeval::[{rs458}==2]
:
endif::[]
-
Document attribute references are expanded before the expression is evaluated.
-
If an attribute reference is undefined then the expression is considered false.
Take a look at the *.conf configuration files in the AsciiDoc
distribution for examples of conditional inclusion macro usage.
The eval, sys and sys2 block macros exhibit the same behavior as their same named system attribute references. The difference is that system macros occur in a block macro context whereas system attributes are confined to inline contexts where attribute substitution is enabled.
The following example displays a long directory listing inside a literal block:
------------------ sys::[ls -l *.txt] ------------------
|
Note
|
There are no block macro versions of the eval3 and sys3 system attributes. |
The template block macro allows the inclusion of one configuration
file template section within another. The following example includes
the [admonitionblock] section in the [admonitionparagraph]
section:
[admonitionparagraph] template::[admonitionblock]
-
The
template::[]macro is useful for factoring configuration file markup. -
template::[]macros cannot be nested. -
template::[]macro expansion is applied after all configuration files have been read.
Passthrough macros are analogous to passthrough blocks and are
used to pass text directly to the output. The substitution performed
on the text is determined by the macro definition but can be overridden
by the <subslist>. The usual syntax is
<name>:<subslist>[<passtext>] (for inline macros) and
<name>::<subslist>[<passtext>] (for block macros). Passthroughs, by
definition, take precedence over all other text substitutions.
- pass
-
Inline and block. Passes text unmodified (apart from explicitly specified substitutions). Examples:
pass:[<q>To be or not to be</q>] pass:attributes,quotes[<u>the '{author}'</u>] - asciimath, latexmath
-
Inline and block. Passes text unmodified. Used for mathematical formulas.
- +++
-
Inline and block. The triple-plus passthrough is functionally identical to the pass macro but you don’t have to escape
]characters and you can prefix with quoted attributes in the inline version. Example:Red [red]+++`sum_(i=1)\^n i=(n(n+1))/2`$+++ AsciiMath formula
- $$
-
Inline and block. The double-dollar passthrough is functionally identical to the triple-plus passthrough with one exception: special characters are escaped. Example:
$$`[[a,b],[c,d]]((n),(k))`$$
- `
-
Text quoted with single backtick characters constitutes an inline literal passthrough. The enclosed text is rendered in a monospaced font and is only subject to special character substitution. This makes sense since monospace text is usually intended to be rendered literally and often contains characters that would otherwise have to be escaped. If you need monospaced text containing inline substitutions use a plus character instead of a backtick.
Each entry in the configuration [macros] section is a macro
definition which can take one of the following forms:
<pattern>=<name>[<subslist]-
Inline macro definition.
<pattern>=#<name>[<subslist]-
Block macro definition.
<pattern>=+<name>[<subslist]-
System macro definition.
<pattern>-
Delete the existing macro with this
<pattern>.
<pattern> is a Python regular expression and <name> is the name of
a markup template. If <name> is omitted then it is the value of the
regular expression match group named name. The optional
[<subslist] is a comma-separated list of substitution names enclosed
in [] brackets, it sets the default substitutions for passthrough
text, if omitted then no passthrough substitutions are performed.