AsciiDoc Syntax Cheatsheet

The definitive manual on AsciiDoc syntax is in the Asciidoctor User Manual. To help people get started, however, here is a simpler cheat sheet.

AsciiDoc vs Asciidoctor Syntax

We use tools from the Asciidoctor project to build the HTML version of the Ref Guide. Asciidoctor is a Ruby port of the original AsciiDoc project, which was mostly abandoned several years ago.

While much of the syntax between the two is the same, there are many conventions supported by Asciidoctor that did not exist in AsciiDoc. While the Asciidoctor project has tried to provide back-compatibility with the older project, that may not be true forever. For this reason, it’s strongly recommended to only use the Asciidoctor User Manual as a reference for any syntax that’s not described here.

Basic AsciiDoc Syntax

Bold

Put asterisks around text to make it bold.

More info: http://asciidoctor.org/docs/user-manual/#bold-and-italic

Italics

Use underlines on either side of a string to put text into italics.

More info: http://asciidoctor.org/docs/user-manual/#bold-and-italic

Headings

Equal signs (=) are used for heading levels. Each equal sign is a level. Each page can only have one top level (i.e., only one section with a single =).

Levels should be appropriately nested. During the build, validation occurs to ensure that level 3s are preceded by level 2s, level 4s are preceded by level 3s, etc. Including out-of-sequence heading levels (such as a level 3 then a level 5) will not fail the build, but will produce an error.

More info: http://asciidoctor.org/docs/user-manual/#sections

Code Examples

Use backticks ` for text that should be monospaced, such as code or a class name in the body of a paragraph.

More info: http://asciidoctor.org/docs/user-manual/#mono

Longer code examples can be separated from text with source blocks. These allow defining the syntax being used so the code is properly highlighted.

Example Source Block
[source,xml]
<field name="id" type="string" indexed="true" stored="true" required="true" multiValued="false" />

If your code block will include line breaks, put 4 hyphens (----) before and after the entire block.

More info: http://asciidoctor.org/docs/user-manual/#source-code-blocks

Source Block Syntax Highlighting

The HTML output uses Rouge to add syntax highlighting to code examples. This is done by adding the language of the code block after the source, as shown in the above example source block (xml in that case).

Rouge has a long selection of lexers available. You can see the full list at https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers. Use one of the valid short names to get syntax highlighting for that language.

Ideally, we will have an appropriate lexer to use for all source blocks, but that’s not possible. When in doubt, choose text, or leave it blank.

Importing Code Snippets from Other Files

The build system has the ability to "include" snippets located in other files — even non-AsciiDoc files such as *.java source code files.

Snippets are bounded by "tag" comments placed at the start and end of the section you would like to import. Opening tags look like: // tag::snippetName[]. Closing tags follow the format: // end::snippetName[]. Snippets can be dropped into an .adoc file using an include directive, following the format: include::PathToFileWithSnippet[tag=snippetName]. Note that when relative paths are provided in these directives, those paths are resolved relative to the location of the AsciiDoc file that the include appears in.

Snippets can be included directly from any file in the Lucene/Solr GIT repo by refering to a solr-root-path variable prior to the file path, for example:

[source,java,indent=0]
----
include::{solr-root-path}core/src/java/org/apache/solr/core/SolrCore.java[tag=something]
----

When building the Guide, the solr-root-path attribute will be automatically set correctly for the (temporary) build/solr-ref-guide/content directory used by Ant.

In order for editors (such as ATOM) to be able to offer "live preview" of the *.adoc files using these includes, the solr-root-path attribute must also be set as a document level attribute in each file, with the correct relative path.

For example, using-solrj.adoc sets solr-root-path in its header, along with an example-source-dir attribute (that depends on solr-root-path) in order to reduce redundancy in the many include:: directives it specifies…​

= Using SolrJ
:solr-root-path: ../../
:example-source-dir: {solr-root-path}solrj/src/test/org/apache/solr/client/ref_guide_examples/
...
[source,java,indent=0]
----
include::{example-source-dir}UsingSolrJRefGuideExamplesTest.java[tag=solrj-solrclient-timeouts]
----
...
[source,java,indent=0]
----
include::{example-source-dir}UsingSolrJRefGuideExamplesTest.java[tag=solrj-other-apis]
----
...

For more information on the include directive, see the documentation at http://asciidoctor.org/docs/user-manual/#include-partial.

Block Titles

Titles can be added to most blocks (images, source blocks, tables, etc.) by simply prefacing the title with a period (.). For example, to add a title to the source block example above:

.Example ID field
[source,xml]
<field name="id" type="string" indexed="true" stored="true" required="true" multiValued="false" />

When converting content to HTML, Asciidoctor will automatically render many link types (such as http: and mailto:) without any additional syntax.

However, you can add a name to a link by adding the URI followed by square brackets:

http://lucene.apache.org/solr[Solr Website]

A warning up front, linking to other pages can be a little bit painful. There are slightly different rules depending on the type of link you want to create, and where you are linking from.

The build process includes a validation for internal or inter-page links, so if you can build the docs locally, you can use that to verify you constructed your link properly (or pay attention to the Jenkins build after your commit).

With all of the below examples, you can add text to display as the link title by adding a comma after the section reference followed by the display text, as in:

<<schema-api.adoc#modify-the-schema,Modify the Schema>>

Link to a Section on the Same Page

To link to an anchor (or section title) on the same page, you can simply use double angle brackets (<< >>) around the anchor/heading/section title you want to link to. Any section title (a heading that starts with equal signs) automatically becomes an anchor during conversion and is available for deep linking.

Example

If I have a section on a page that looks like this (from defining-fields.adoc):

== Field Properties

Field definitions can have the following properties:

To link to this section from another part of the same defining-fields.adoc page, I simply need to put the section title in double angle brackets, as in:

See also the <<Field Properties>> section.

The section title will be used as the display text; to customize that add a comma after the the section title, then the text you want used for display.

More info: http://asciidoctor.org/docs/user-manual/#internal-cross-references

When linking to any section (on the same page or another one), you must also be aware of any pre-defined anchors that may be in use (these will be in double brackets, like [[ ]]). When the page is converted, those will be the references your link needs to point to.

Example

Take this example from configsets-api.adoc:

[[configsets-create]]
== Create a ConfigSet

To link to this section, there are two approaches depending on where you are linking from:

  • From the same page, simply use the anchor name: <<configsets-create>>.

  • From another page, use the page name and the anchor name: <<configsets-api.adoc#configsets-create>>.

Link to Another Page

To link to another page or a section on another page, you must refer to the full filename and refer to the section you want to link to.

Unfortunately, when you want to refer the reader to another page without deep-linking to a section, you cannot simply put the other file name in angle brackets and call it a day. You must always link to a specific section. If all you want is a reference to the top of another page, you can use the implicit id of the page — the filename w/o the .adoc extension — as your anchor reference.

Example

To construct a link to the upgrading-solr.adoc page, we need to refer to the file name (upgrading-solr.adoc), then use the page id (upgrading-solr) as the anchor reference. As in:

For more information about upgrades, see <<upgrading-solr.adoc#upgrading-solr>>.

Link to a Section on Another Page

Linking to a section is the same conceptually as linking to the top of a page, you just need to take a little extra care to format the anchor ID in your link reference properly.

When you link to a section on another page, you must make a simple conversion of the title into the format the section ID will be created during the conversion. These are the rules that transform the sections:

  • All characters are lower-cased.

    • Using security.json with Solr becomes using security.json with solr

  • All non-alpha characters are removed, with the exception of hyphens (so all periods, commas, ampersands, parentheses, etc., are stripped).

    • using security.json with solr becomes using security json with solr

  • All whitespaces are replaced with hyphens.

    • using security json with solr becomes using-security-json-with-solr

Example

The file schema-api.adoc has a section "Modify the Schema" that looks like this:

== Modify the Schema

`POST /_collection_/schema`

To link from to this section from another page, you would create a link structured like this:

  • the file name of the page with the section (schema-api.adoc),

  • then the hash symbol (#),

  • then the converted section title (modify-the-schema),

  • then a comma and any link title for display.

The link in context would look like this:

For more information, see the section <<schema-api.adoc#modify-the-schema,Modify the Schema>>.

More info: http://asciidoctor.org/docs/user-manual/#inter-document-cross-references

Ordered and Unordered Lists

AsciiDoc supports three types of lists:

  • Unordered lists

  • Ordered lists

  • Labeled lists

Each type of list can be mixed with the other types. So, you could have an ordered list inside a labeled list if necessary.

Unordered Lists

Simple bulleted lists need each line to start with an asterisk (*). It should be the first character of the line, and be followed by a space.

These lists also need to be separated from the

More info: http://asciidoctor.org/docs/user-manual/#unordered-lists

Ordered Lists

Numbered lists need each line to start with a period (.). It should be the first character of the line, and be followed by a space.

This style is preferred over manually numbering your list.

More info: http://asciidoctor.org/docs/user-manual/#ordered-lists

Labeled Lists

These are like question & answer lists or glossary definitions. Each line should start with the list item followed by double colons (::), then a space or new line.

Labeled lists can be nested by adding an additional colon (such as :::, etc.).

If your content will span multiple paragraphs or include source blocks, etc., you will want to add a plus sign (+) to keep the sections together for your reader.

We prefer this style of list for parameters because it allows more freedom in how you present the details for each parameter. For example, it supports ordered or unordered lists inside it automatically, and you can include multiple paragraphs and source blocks without trying to cram them into a smaller table cell.

More info: http://asciidoctor.org/docs/user-manual/#labeled-list

Images

There are two ways to include an image: inline or as a block.

Inline images are those where text will flow around the image. Block images are those that appear on their own line, set off from any other text on the page.

Both approaches use the image tag before the image filename, but the number of colons after image define if it is inline or a block. Inline images use one colon (image:), while block images use two colons (image::).

Block images automatically include a caption label and a number (such as Figure 1). If a block image includes a title, it will be included as the text of the caption.

Optional attributes allow you to set the alt text, the size of the image, if it should be a link, float and alignment.

More info: http://asciidoctor.org/docs/user-manual/#images

Tables

Tables can be complex, but it is pretty easy to make a basic table that fits most needs.

Basic Tables

The basic structure of a table is similar to Markdown, with pipes (|) delimiting columns between rows:

|===
| col 1 row 1 | col 2 row 1|
| col 1 row 2 | col 2 row 2|
|===

Note the use of |=== at the start and end. For basic tables that’s not exactly required, but it does help to delimit the start and end of the table in case you accidentally introduce (or maybe prefer) spaces between the rows.

Header Rows

To add a header to a table, you need only set the header attribute at the start of the table:

[options="header"]
|===
| header col 1 | header col 2|
| col 1 row 1 | col 2 row 1|
| col 1 row 2 | col 2 row 2|
|===

Defining Column Styles

If you need to define specific styles to all rows in a column, you can do so with the attributes.

This example will center all content in all rows:

[cols="2*^" options="header"]
|===
| header col 1 | header col 2|
| col 1 row 1 | col 2 row 1|
| col 1 row 2 | col 2 row 2|
|===

Alignments or any other styles can be applied only to a specific column. For example, this would only center the last column of the table:

[cols="2*,^" options="header"]
|===
| header col 1 | header col 2|
| col 1 row 1 | col 2 row 1|
| col 1 row 2 | col 2 row 2|
|===

Many more examples of formatting:

More Options

Tables can also be given footer rows, borders, and captions. You can determine the width of columns, or the width of the table as a whole.

CSV or DSV can also be used instead of formatting the data in pipes.

More info: http://asciidoctor.org/docs/user-manual/#tables

Admonitions (Notes, Warnings)

AsciiDoc supports several types of callout boxes, called "admonitions":

  • NOTE

  • TIP

  • IMPORTANT

  • CAUTION

  • WARNING

It is enough to start a paragraph with one of these words followed by a colon (such as NOTE:). When it is converted to HTML, those sections will be formatted properly - indented from the main text and showing an icon inline.

You can add titles to admonitions by making it an admonition block. The structure of an admonition block is like this:

.Title of Note
[NOTE]
====
Text of note
====

In this example, the type of admonition is included in square brackets ([NOTE]), and the title is prefixed with a period. Four equal signs give the start and end points of the note text (which can include new lines, lists, code examples, etc.).

More info: http://asciidoctor.org/docs/user-manual/#admonition