FAQs and Troubleshooting

Frequently Asked Questions

Does Asciidoctor only encode in US-ASCII?

No. Asciidoctor encodes in UTF-8 and has full Unicode support.
How do I enable syntax highlighting in the deck.js backend?
You begin by setting the source-highlighter attribute to one of the accepted values, such as coderay.
:source-highlighter: coderay
That only gets you half way, though. The problem is that Asciidoctor only performs syntax highlighting when the "base" backend attribute (i.e., basebackend attribute) is html. The basebackend attribute is determined by removing the trailing numbers from the backend name. For instance, html5 becomes html. However, deckjs becomes…deckjs. There in lies our problem (see issue #891).

The workaround is to set the backend to html5 (or just don’t set it) and point the -T command argument to the haml/deckjs folder under the asciidoctor-backends directory. For example:
$ asciidoctor -T /path/to/asciidoctor-backends/haml/deckjs deck.adoc
Notice that the backend attribute is not set. The templates will be used in exactly the same way as if you had set the backend to deckjs, except this time syntax highlighting will work!
If you want to have CodeRay embed the styles inline instead of using CSS classes, set the following attribute in your AsciiDoc document:

:coderay-css: style

How do I make relative links to other AsciiDoc files to work correctly on GitHub?

In certain environments, such as GitHub and the browser preview extensions, you view the generated HTML through the AsciiDoc source URL. This has consequences for inter-document cross references.

Since the default suffix for relative links in the html5 backend is .html, the inter-document cross references end 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. You can achieve this behavior by setting the outfilesuffix attribute to the value as .adoc, as the example below shows.

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

See the <<README#,README>>.

We could also write the link as link:README{outfilesuffix}[README].

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

You probably don’t want to set outfilesuffix to .adoc without the ifdef condition as it could result in Asciidoctor overwriting input files when you run it locally (though there’s some protection against this).

While outfilesuffix 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:

:relfileprefix: ../
:outfilesuffix: /

Now, the cross reference +<<filename#,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 is the internet mime type (aka MIME type) for AsciiDoc?
The first idea that emerged from the Mimetype for AsciiDoc discussion on the Asciidoctor mailinglist was:
text/x-asciidoc
Recently, the internet media type text/markdown was registered for Markdown, so another option to consider is:
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 selector .openblock so that you can see its boundaries.
Why don’t URLs containing underscores (_) or carets ({caret}) work after they’re rendered?
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.

= Document Title :link-with-underscores: http://www.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.

This URL has repeating underscores pass:macros[http://www.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.

This URL has repeating underscores link:++http://www.asciidoctor.org/now_this__link_works.html++[].
For more information, see issue #625.