Asciidoc user manual

Blank lines are required before and after a list. Additionally, blank lines are permitted, but not required, between list items. Was your instinct to use a hyphen - instead of an asterisk to mark list items? Guess what? That works too! If you have adjacent lists, they have the tendency to want to fuse together. In Asciidoctor 1.

Since Asciidoctor 1. Keep in mind, however, that some interfaces will begin flattening lists after a certain depth. GitHub starts flattening list after 10 levels of nesting. A new level is created for each unique marker encountered. Sometimes, we need to number the items in a list. Instinct might tell you to prefix each item with a number, like in this next list:.

The above works, but since the numbering is obvious, the AsciiDoc processor will insert the numbers for you if you omit them:. If you decide to use number for your ordered list, you have to keep them sequential. This differs from other lightweight markup languages. For instance, you can type:.

However, in general the best practice is to use the start attribute to configure this sort of thing:. You can give a list a title by prefixing the line with a dot immediately followed by the text without leaving any space after the dot.

AsciiDoc selects a different number scheme for each level of nesting. Asciidoctor works hard to infer the relationships between the items that are most intuitive to us humans. You can override the number scheme for any level by setting its style the first positional entry in a block attribute list. You can also set the starting number using the start attribute:. A description list often abbreviate as dlist is useful when you need to include a description or supporting text for one or more terms.

Each item in a description list consists of:. By default, the content of each item is displayed below the description when rendered. If you want the description and content to appear on the same line, add the horizontal style to the list. The content of a description list can be any AsciiDoc element. For instance, we could rewrite the grocery list from above so that each aisle is a description rather than a parent outline list item. Description lists are quite lenient about whitespace, so you can spread the items out and even indent the content if that makes it more readable for you:.

Finally, you can mix and match the three list types within a single hybrid list. You can think of these like implicit macro names the bare email address being a special case. Since the URL in the example below begins with a protocol in this case https followed by a colon , Asciidoctor will automatically turn it into a hyperlink when it is processed.

When a URL does not start with one of the common schemes , or the URL is not surrounded by word boundaries, you must use the link macro. The link macro is a stronger version of a URI macro, which you can think of like an unconstrained macro. The URL is preceded by link: and followed by square brackets. The square brackets may include optional link text. The URL is used for the text of the link if link text is not specified. Prior to 1. Since 1. If you want attributes in the link macro to be parsed, you must set the linkattrs document attribute in the header.

When attribute parsing is enabled, you can then specify the name of the target window using the window attribute. Chat with other Asciidoctor users on the mailing list. If you want to link to an external file relative to the current document, use the link macro in front of the file name.

A link to another location within an AsciiDoc document or between AsciiDoc documents is called a cross reference also referred to as an xref. In Asciidoctor, the inline xref macro is used to create cross references also called in-text or page citations to content elements sections, blocks, or phrases that have an ID regardless of whether that ID is explicit or auto-generated.

You create a cross reference by enclosing the ID of the target block or section or the path of another document with an optional anchor in double angled brackets.

You can also link to a block or section using the title by referencing its title, referred to as a natural cross reference. The title must contain at least one space character or contain at least one uppercase letter. Converters usually use the reftext of the target as the default text of the link. When the document is parsed, attribute references in the reftext are substituted immediately. When the reftext is displayed, additional reftext substitutions are applied to the text specialchars, quotes, and replacements.

You can override the reftext of the target by specifying alternative text at the location of the cross reference. After the ID, add a comma and then enter the custom text you want the cross reference to display. Cross references can also be used to create a link to a file relative to the current document.

For links to another AsciiDoc document, this is the preferred way. In both cases, this syntax will also work if you are inside the document you are referring to.

This is useful if you are sharing the same link across multiple documents. In the link that is created from the inter-document cross reference, the source file extension is replaced with the value of the outfilesuffix attribute.

To customize the file extension used in the target of the link, simply change the value of this attribute. Image references are similar to links since they are also references to URLs or files. The difference, of course, is that they display the image in the document. To include an image on its own line i. You can also give the image an id, a title i.

The title of a block image is displayed underneath the image when rendered. If you want to include an image inline, use the image: prefix instead notice there is only one colon :. If paragraphs and lists are the meat of the document, then titles and sections are its bones. All titles are optional in AsciiDoc. This section will define each title type and explain how and when to use them. Just as every e-mail has a subject, every document typically has a title. The title goes at the top of an AsciiDoc document.

This syntax is the simplest and thus recommended way to declare a document title. The document title is part of the document header.

So, what else can go in the header? Good question. Notice the blank line between the title line and the first line of content in the previous example. This blank line separates the document header from the document body in this case a paragraph. In all, the document header contains the title, author, revision information and document-wide attributes. Your document now has a title, but what about an author?

Just as every e-mail has a sender, every document must surely have an author. There are two optional lines of text you can add immediately below the document title for defining common document attributes:.

The header now contains a document title, an author, a revision number, and a date. This information will typically be displayed as a formatted header at the top of the output document. Attributes are one of the features that sets AsciiDoc apart from other lightweight markup languages. You can use attributes to toggle features or to store reusable or replacement content. Most often, attributes are defined in the document header. An attribute entry consists of a name surrounded by colons at the beginning of the line followed by at least one space, then the content.

The content is optional. Now you can refer to this attribute anywhere in the document where attribute substitution is performed by surrounding the name in curly braces:. Attributes are also commonly used to store URLs, which can get quite lengthy. Document attributes can also be used to toggle settings or set configuration variables that control the output generated by the AsciiDoc processor.

For example, to include a table of contents in your document, you can define the toc attribute:. You can also set the base path to images default: empty , icons default:.

When you find yourself typing the same text repeatedly, or text that often needs to be updated, consider assigning it to a document attribute and use that instead.

Sections partition the document into a content hierarchy. In AsciiDoc, sections are defined using section titles. A section title uses the same syntax as a document title, except the line may begin with two to six equal signs instead of just a single equal sign.

The number of equal signs represents the nesting level using a 0-based index. Here are all the section levels permitted in an AsciiDoc document for an article doctype, the default , shown below the document title:. A document can only have multiple level 0 sections if the doctype is set to book. Content above the first section after the document title is part of the preamble. Once the first section is reached, content is associated with the section that precedes it:. What is the Asciidoctor license?

Using AsciiDoc and Asciidoctor to write documentation article by vogella. Convert your first document. A template containing the most common content structures and markup used in an AsciiDoc article document.

This Ruby library is often referred to as Asciidoctor core. AsciidoctorJ bundles all gems that are required for executing Asciidoctor and wraps it into a Java API so that Asciidoctor can be used in Java like any other Java library. The following table gives you an idea of how to use these interfaces. You compose documents using the AsciiDoc language , which is a text-based writing format. The AsciiDoc language was designed to be unobtrusive and concise to simplify writing and make it more pleasant.

But AsciiDoc itself is not a publishing format. It can also convert it to formats which themselves can be processed by a publishing toolchain, such as DocBook. Since AsciiDoc is not published as is, the processing step provides an opportunity to augment the document by expanding shorthand codes, layering in integrations, and applying a pleasant visual style.

That augmentation is a large part of what Asciidoctor does. It reads the AsciiDoc source, parses it into a document model, and converts it to a publishable format such as HTML using a converter. Asciidoctor enriches the HTML it produces from AsciiDoc by applying a default stylesheet , adding stylistic icons, and syntax highlighting source blocks. There are three variants of the core Asciidoctor processor that all share the same code base.

With few exceptions, these variants all provide the full Asciidoctor experience. From these three implementations extend a host of extensions, build tool integrations, and tooling plugins in the Asciidoctor community and beyond. Transpiles Asciidoctor into JavaScript so you can run it in the browser or a Node.

Convert your content from AsciiDoc automatically when you run your build. Encapsulate assets, configuration profiles, and extensions for your publishing process in your build scripts. Even extract and convert AsciiDoc inside Javadoc comments or include snippets from your test suite. Author HTML slide presentations in AsciiDoc without having to wrestle with the clutter of HTML or add diagrams to the output file that are generated from plain text markup inside your AsciiDoc document using extensions.

The possiblities are boundless! Want to build a documentation site like this one?