Install AsciiDoc on the commandline (Mac OSX)

Posted on in Environment

When you are not really used to work on the command line it might seem hard to install AsciiDoc on your Mac OSX machine. These are the commands I used for installing it on the command line. Actually it's pretty easy with the use of the Mac Port tool.

  1. Download Mac Port and run the install wizard.
  2. Open a new terminal and install AsciiDoc via Port:
sudo port install asciidoc
  1. In your terminal install dblatex via Port:
sudo port install dblatex

Now you can start writing *.txt files with ASCIIDOCS format which can be exported to epub:

a2x -f epub ~/Documents/book.txt

or PDF:

a2x -f pdf --fop ~/Documents/book.txt

or html:

a2x -f xhtml ~/Documents/book.txt

Note: ~/Documents/book.txt points to the path with my textfile.
It's possible to skip the xml lint validation, by adding the following parameters:

--verbose --no-xmllint


  1. Anthony Whitford says on
    May 19, 2013 at 1:29 am

    Why do you need to install dblatex too?

    • Lee says on
      May 28, 2013 at 7:53 am

      Hi Anthony,
      dblatex is a program that transforms your SGML/XMLDocBook documents to DVI, PostScript or PDF.
      I use it for generating PDF files and they look great!

  2. Xiang says on
    May 29, 2013 at 1:20 pm

    Thanks for the concise guide.
    However from your example, there is no need to install dblatex.
    –fop means to use fop to produce pdf file.
    And for me, when exec a2x, I got the “failed to load external entity “” error, and after set the environment variable XML_CATALOG_FILES=/usr/local/etc/xml/catalog , I also add the option –xsltproc-opts=–catalogs to a2x to solve this. Hope this will help others with similar problem.

    Also option –xsltproc-opts=–novalid will speed a lot.

  3. Paul Higham says on
    August 5, 2013 at 5:04 pm

    After following these instructions I could get an html rendition of an asciidoc source, but the command

    a2x -f pdf –verbose

    gives an error, essentially stating that the docbook.dtd is not installed. There is an excellent explanation at

    of what the problem is and what to do about it but it is quite involved. I am wondering if anyone has found a simpler installation procedure because the MacPorts one does not seem to be complete.

  4. Scott says on
    August 5, 2013 at 11:47 pm

    Thank you for a simple approach to asciidoc on the Mac – you saved me a lot of time!

  5. Paul Higham says on
    August 20, 2013 at 7:19 pm

    Instead of the rather involved process I pointed at in a prior comment I did something much simpler that worked in my case and that was to add the following line to my .bash_profile in my home directory

    export XML_CATALOG_FILES=/opt/local/etc/xml/catalog

    and now a2x works without having to use the –no-xmllnt option

  6. Fantasy Warlord says on
    September 25, 2014 at 4:01 pm

    Magnificent website. A lot of helpful info here. I am sending it to some friends ans also sharing in delicious.
    And of course, thanks on your sweat!

Post a Comment

Your email is never published nor shared.
Required fields are marked *