Generate HTML from AsciiDoc

Asciidoctor’s default output format is HTML (specifically HTML 5). That means when you run Asciidoctor without any parameters, it will produce HTML. This page explains how to use Asciidoctor to convert AsciiDoc to HTML.

Backend and converter

Asciidoctor’s built-in HTML converter is registered for the html and html5 backends. The HTML converter generates HTML 5 that’s styled with CSS3. It may include JavaScript to support additional integrations, such as client-side syntax highlighting.

Backend names	`html`, `html5`
Converter class	`Asciidoctor::Converter::Html5Converter`
Output format	HTML
Output file extension	.html

A standalone HTML document generated by the built-in HTML converter loads web fonts from Google Fonts, which are then referenced by the default stylesheet. The default stylesheet makes use of web fonts to ensure the document renders consistently across platforms. Concerns have been raised that Google Fonts do not comply with GDPR. If this presents a problem, you can opt out of the use of Google Fonts. When this is done, the default stylesheet reverts to using generic font families (e.g., sans-serif), which are mapped to system fonts by your browser. The consequence is that the appearance of the document will be different and system dependent due to a reliance on system fonts.

If the backend name is prefixed with x (e.g., xhtml), the converter will generate XHTML, the XML variant of HTML.

Generate HTML

In this section, we’ll create a sample document, then process and convert it with Asciidoctor’s built-in HTML converter.

Create and save an AsciiDoc document

To follow along with the steps below, use your own AsciiDoc file or copy the contents of Example 1 into a new plaintext file.

Example 1. my-document.adoc

= The Dangers of Wolpertingers
:url-wolpertinger: https://en.wikipedia.org/wiki/Wolpertinger

Don't worry about gumberoos or splintercats.
Something far more fearsome plagues the days, nights, and inbetweens.
Wolpertingers.

== Origins

Wolpertingers are {url-wolpertinger}[ravenous beasts].

Make sure to save the file with the .adoc file extension.

Convert an AsciiDoc document to HTML

To convert my-document.adoc to HTML from the command line:

Open a terminal.
Switch to the directory that contains the my-document.adoc document
Call the Asciidoctor processor with the asciidoctor command, followed by the name of the document.
$ asciidoctor my-document.adoc
Remember, Asciidoctor’s default converter is html5, so it isn’t necessary to specify it with the -b command.
You won’t see any messages printed to the console. Type ls to view the files in the directory or navigate to the directory in a file manager. You should see a new file named my-document.html.
$ ls my-document.adoc my-document.html
Asciidoctor derives the name of the output document from the name of the input document.
Open my-document.html in your web browser. Your document should look like the image below.

The document’s text, titles, and link are styled by the default Asciidoctor stylesheet, which is embedded in the HTML output. As a result, you could save my-document.html to any computer and it will look the same.
If you want to preview the HTML in the terminal, you can use this command instead:
```
$ asciidoctor my-document.adoc -o - | w3m - -T text/html
```

Generate XHTML

Backend names	`xhtml`, `xhtml5`
Converter class	`Asciidoctor::Converter::Html5Converter`
Output format	XML variant of HTML
Output file extension	.html

Produce XHTML using the xhtml5 backend option

$ asciidoctor -b xhtml5 my-document.adoc

To produce XHTML instead of HTML when using converter templates, set the htmlsyntax attribute to xml in addition to the backend option:

Produce XHTML using custom templates

$ asciidoctor -T /path/to/templates -b slides -a htmlsyntax=xml my-document.adoc

Black Box Decoded: XHTML and htmlsyntax

XHTML output is a special mode of the built-in HTML5 converter. It is activated by prefixing the backend value with x (e.g., xhtml or xhtml5). This hint implicitly assigns the htmlsyntax attribute to the value xml, which normally has the value html.

For all other converters, the htmlsyntax attribute is not set explicitly. If you want a converter template that’s written in Slim or Haml to output XHTML instead of the default HTML, you need to set the htmlsyntax attribute to xml explicitly. Asciidoctor will pass on this preference to the Slim or Haml template engine by setting the :format option to :html5.