Generate HTML from AsciiDoc

HTML 5 converter

Asciidoctor’s default output format is HTML.

html

The HTML 5 converter (html or html5) generates HTML 5 styled with CSS3.

Generate HTML using the html5 converter

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

  1. 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].

  2. 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:

  1. Open a terminal.

  2. Switch to the directory that contains the my-document.adoc document

  3. 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.

  4. 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.

  5. Open my-document.html in your web browser. Your document should look like the image below.

    my document

    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.

Generate XHTML

xhtml

The XHTML variant of the HTML 5 converter. To use the XHTML converter, assign xhtml or xhtml5 to the backend option.

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 simply 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.