Using AsciiDoc (asciidoctor) in Marked

Contributed by Adrian Kosmaczewski

1. Make sure that you are not using the ruby that comes by default with macOS, but the one installed with Homebrew. If needed, brew link --overwrite ruby to get everybody in the same line. This means, get rid of rbenv temporarily and then install asciidoctor.
   
2. Install asciidoctor and related gems as root (sudo gem install asciidoctor).
   
3. Configure Marked 2 using the Preferences > Advanced > Enable Custom Processor option:
   
   • Path: /usr/local/bin/asciidoctor
   • Args: --base-dir /path/to/your/root/folder/ --safe-mode safe --attribute confdir=../_conf --attribute imagesdir=../images --attribute datadir=../data --attribute codedir=../code --attribute toc --section-numbers --backend html5 --doctype book --out-file - -
     
     • Pay attention to that double dash with a space at the end of the arguments!
     • It is required to specify the --base-dir and —safe-mode options for asciidoctor, otherwise the images, code and other artifacts are not included properly.

Additional information

Taken from a Gist by Dan Allen.

Marked is an OSX application to preview Markdown syntax in HTML. It's possible to configure AsciiDoc as an custom Markdown processor to create the HTML for your AsciiDoc files.

Configuration

In the behavior settings of Marked, complete the following steps:

1. enable Custom Markdown Processor

2. enter path to asciidoc command (something like /usr/bin/asciidoc or /opt/local/bin/asciidoc)

3. enter --backend html5 -o - - as args (the -` at the end sends the output as STDOUT)

This sends the current document to STDIN and displays the generated HTML as STDOUT.

Resolving include files

One of the hiccups with using AsciiDoc with Marked are include files, such as:

include::myfile.txt[]

The asciidoc command dies when it hits the first include file, since it tries to resolve it from the working directory, which probably isn't the directory of your document.

Here are a few ideas for how to work around this problem.

Option A

You can switch the current working directory to the directory of your document using a shell script (or commandline chain) that wraps the asciidoc command. You would need some way for Marked to pass the directory of the document so the script knows where it needs to switch.

Option B

You can set the absolute include directory as an attribute in your AsciiDoc document, then prefix all include paths with this attribute. For example:

= Document Title
:includedir: /path/to/document/

Unresolved directive in <stdin> - include::{includedir}myfile.txt[]

You can override the includedir attribute from the commandline when you process the document in a different context. Consider the setting in the document as the fallback. Another option is to add it to the args to the custom markdown processor, such as -a includedir=/path/to/document/.

Option C

You can use Asciidoctor, which allows you to set the base directory from the commandline. I'm not sure how to get the document directory from Marked, so let's just assume for now that you have to hard code it. You would specify the path to asciidoctor instead of asciidoc and append the following to the args: -B /path/to/documents

Asciidoctor has the benefit that it's about 40x as fast as AsciiDoc. For instance, the 17,000 line (3,750 blocks) Enterprise Web Book from O'Reilly renders to HTML5 in 0.85 seconds on an ASUS ZenBook Prime notebook :)

Reference: Using AsciiDoc with Marked (Google discussion post)