FAQs

Does Asciidoctor only process text that is US-ASCII encoded?

No. Asciidoctor has full Unicode support (UTF-8 by default, UTF-16 with a BOM). 👌

The “Ascii” in AsciiDoc and Asciidoctor merely refers to the range of characters from which the special characters in the syntax (section title markers, block delimiters, macro and block names, etc.) are drawn. In other words, you only need to use characters from US-ASCII to form the structure of an AsciiDoc document. The content itself, which includes attribute values, may contain characters from any character plane in Unicode.

Asciidoctor assumes input is encoded in UTF-8 and it encodes output documents in UTF-8 as well.

In certain environments, such as a web interface for a source repository (e.g., GitHub.com) or the browser preview extensions, you see the generated HTML when you visit the URL of the AsciiDoc source file. This has consequences for inter-document cross references.

Since the default suffix for inter-document cross references in the html5 backend is .html, the resulting link created in these environments ends up pointing to non-existent HTML files. In this case, you need to change the inter-document cross references to refer to other AsciiDoc source files instead.

The file extension chosen for inter-document cross references is controlled by the relfilesuffix attribute. By default, this attribute is not set and the value of the outfilesuffix is used instead. If you want to change the file extension that gets used, you can do so by setting the relfilesuffix attributee.

The following example demonstrates how to use the relfilesuffix attribute to control the file extension for inter-docuemnt cross references on GitHub and the browser preview extension.

1
2
3
4
5
6

= Document Title
ifdef::env-github,env-browser[:relfilesuffix: .adoc]

See the <<README.adoc,README>>.

We could also write the link as link:README{relfilesuffix}[README].
This configuration is not actually necessary on GitHub and GitLab since those environments now set the value of relfilesuffix to match the file extension of the source file. However, it may still be required in other GitHub-like environments, so it’s worth noting.

The links in the generated document will now point to README.adoc instead of the default, README.html.

While relfilesuffix gives you control over the end of the resolved path for an inter-document cross reference, the relfileprefix attribute gives you control over the beginning of the path. When resolving the path of an inter-document cross reference, if the relfileprefix attribute is set, the value of this attribute gets prepended to the path. Let’s look at an example of when these two attributes are used together.

A common practice in website architecture is to move files into their own folder to make the path format agnostic (called “indexify”). For example, the path filename.html becomes filename/ (which targets filename/index.html). However, this is problematic for inter-document cross references. Any cross reference that resolves to the path filename.html is now invalid since the file has moved to a subfolder (and thus no longer a sibling of the referencing document).

To solve this problem, you can define the following two attributes:

1
2

:relfileprefix: ../
:relfilesuffix: /

Now, the cross reference <<filename.adoc,Label>> will resolve to ../filename/ instead of filename.html. Since this change is specific to the website architecture described, you want to be sure to only set these attributes in that particular environment (either using an ifdef directive or via the API).

What’s the relationship between a converter and a backend?

A converter is the software component in Asciidoctor that performs conversion from AsciiDoc to a publishable format. A backend is an alias—​kind of like a keyword—​that identifies the converter to use.

The backend expresses an intent to transform to a certain format (e.g., html5 for HTML5). But it’s more than just being shorter to type. Multiple converters can bind to (i.e., stake claim to) the same backend in order to provide different approaches for performing that conversion. For example, the backend pdf could activate Asciidoctor PDF, but it’s also possible it means a different implementation. The last converter bound to a backend wins.

What is the media type for AsciiDoc?

A media type, or MIME type, is a code for identifying file formats and format contents transmitted on the Internet.

The first idea for an official MIME type for AsciiDoc came from the Mimetype for AsciiDoc discussion on the Asciidoctor mailinglist:

text/x-asciidoc

Recently, the internet media type text/markdown was registered for Markdown, so a stronger case can now be made for:

text/asciidoc

Either one will do, though it probably makes sense to align with Markdown on this one.

Troubleshooting

Part way through the document, the blocks stop rendering correctly. What went wrong?

When content is not rendered as you expect in the later part of a document, it’s usually due to a delimited block missing its closing delimiter line. The most devious culprit is the open block. An open block doesn’t have any special styling, but its contents have the same restrictions as other delimited blocks, i.e. it can not contain section titles.

To solve this problem, first look for missing delimiter lines. Syntax highlighting in your text editor can help with this. Also look at the rendered output to see if the block styles are extending past where you intended. When working with open blocks, you may need to add custom styles (such as a red border) to the class openblock so you can see its boundaries.

This problem occurs because the markup parser interprets parts of the URL (i.e., the link target) as valid text formatting markup. Most lightweight markup languages have this issue because they don’t use a grammar-based parser. Asciidoctor plans to handle URLs more carefully in the future (see issue #281), which may be solved by moving to a grammar-based parser (see issue #61). Thankfully, there are many ways to include URLs of arbitrary complexity using the AsciiDoc passthrough mechanisms.

Solution A

The simplest way to get a link to behave is to assign it to an attribute.

1
2
3
4

= Document Title
:link-with-underscores: https://asciidoctor.org/now_this__link_works.html

This URL has repeating underscores {link-with-underscores}.

Asciidoctor won’t break links with underscores when they are assigned to an attribute because inline formatting markup is substituted before attributes. The URL remains hidden while the rest of the document is being formatted (strong, emphasis, monospace, etc).

Solution B

Another way to solve formatting glitches is to explicitly specify the formatting you want to have applied to a span of text. This can be done by using the inline pass macro. If you want to display a URL, and have it preserved, put it inside the pass macro and enable the macros substitution, which is what substitutes links.

1

This URL has repeating underscores pass:macros[https://asciidoctor.org/now_this__link_works.html].

The pass macro removes the URL from the document, applies the macros substitution to the URL, and then restores the processed URL to its original location once the substitutions are complete on the whole document.

Alternatively, you can use ++ around the URL only. However, when you use this approach, Asciidoctor won’t recognize it as a URL any more, so you have to use the explicit link prefix.

1

This URL has repeating underscores link:++https://asciidoctor.org/now_this__link_works.html++[].

For more information, see issue #625.