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. If you want to follow along with the examples, download the my-sample.adoc file or use your own AsciiDoc document.

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

    $ cd directory-name
  2. 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-sample.adoc

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

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

    $ ls
    my-sample.adoc  my-sample.html

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

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

    fix ex

    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-sample.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 Working with the API.