Advice on configuring Marked (OSX) to work with AsciiDoc content using AsciiDoc (or Asciidoctor) as a custom Markdown processor, including how to get AsciiDoc includes to work.

marked-asciidoc-content.adoc

Using Marked with AsciiDoc content

Using Marked with AsciiDoc content

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/

link:{includedir}myfile.txt[role=include]

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 (discussion post)

You also may need to suppressing warnings to avoid Marked from getting tripped up by output to stderr. You can now do that using the -q flag.

asciidoctor -q -o - -

You may need to link the stylesheet or include it outright if that causes a crash in the processor.

asciidoctor -q -a stylesheet! -o - -

Thanks for this advice. It is the only reason I bought Marked, since I have other Markdown editors.

I found that, using Asciidoctor, I could suply the following arguments:

-B /Users/mark/… --backend=html5 -

I had to try a couple of times, and I only got it working when I added the -B option before the others.

The advantage to this approach is that the document itself doesn’t need to hard code its location.

I think it’s a logical flaw that relative paths are not calculated from the document location.

This was going strong for me until I broke it.

I found that including multiple = Level 0 headings caused Marked to hang. This is because asciidoctor doesn’t allow that in non-docbook documents.

The solution was to include -d book, so now I have;

-d book -B /Users/mark/… --backend=html5 -

I came about this post while trying to get ditaa diagrams working with marked and asciidoctor as processor.
This is my solution using Option C (using a wrapper script):

#!/usr/local/bin/bash
/usr/local/bin/asciidoctor --backend html5 --doctype book --require asciidoctor-diagram -B $MARKED_ORIGIN -o - - $*

The key thing here is $MARKED_ORIGIN which is passed to the script by marked and can be used as BASEDIR by asciidoctor.
This solved my "ditaa file generation problem" and also works with include files.