Convert Your First AsciiDoc File

Assumptions:

  • You’ve installed Asciidoctor.

  • You’ve confirmed that the Asciidoctor command line interface (CLI) is available on your PATH.

On this page, you’ll learn how to run Asciidoctor on an AsciiDoc document and convert it to HTML.

Generate HTML using the default converter

Let’s generate HTML 5 using Asciidoctor’s default converter and stylesheet from an AsciiDoc document.

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

    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.

  3. Open a terminal and switch (cd) into the directory where your AsciiDoc document is saved.

    $ cd directory-name

  4. Call Asciidoctor with the asciidoctor command, followed by file name of the AsciiDoc document. Since HTML 5 is Asciidoctor’s default output, we don’t need to specify a converter.

    $ asciidoctor my-document.adoc

    As long as the document didn’t contain any syntax errors, you won’t see any messages printed to your terminal.

  5. Type ls to list the files in the directory.

    $ ls
my-document.adoc  my-document.html

    You should see a new file named my-document.html. Asciidoctor derives the name of the output file from the name of the input document.

  6. Open my-document.html in your web browser. The converted document should look like the example below.

    my document

    The document’s text, titles, and link is 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.

Most of the examples in the general documentation use the CLI, but there are usually corresponding API examples under Process AsciiDoc Using the API.