Using AsciiDoc & Asciidoctor for blogging

Editing experience isn’t as good

Most modern editors support AsciiDoc syntax highlighting and sometimes preview, via plugins. But, as expected, these aren’t as well-developed, numerous or as fully featured as the Markdown equivalents. If you’re using the Asciidoctor markdown-a-like syntax for the simple stuff, then you can just tell the editor it’s Markdown, and use the more fully featured markdown support.

Not much native support

If you’re using a Ruby blog engine, it might have native AsciiDoc support, or your blog engine might have a plugin that supports it. Don’t expect every blog engine to support it, though. Some blog engines have an escape hatch that let you use Pandoc or some other custom command to process your content - and while Pandoc does have AsciiDoc support, it’s neither complete nor flawless.

Does native support matter?

Does the fact that the document processing is shelled out to a black box actually affect using AsciiDoc for blogging? Well, it makes publishing a bit slower to a lot slower, depending on the size of your site. But in most blog/publishing systems you have a template that defines the structure of the page with some kind of placeholder that says {{content-goes-here}}. It doesn’t really matter how the content is generated, as long as it is - and as long as the HTML that’s produced lines up with your CSS & is reasonable. Speaking of which…​

Asciidoctor’s built-in HTML output could be better

When asciidoctor processes your .adoc file you can tell it what converter (or “back-end”) you want to use - i.e. what kind of output you want. These are the built-in options. This is what they say about the default HTML converter:

This is technically true, however, while the HTML it produces is technically HTML5, it’s also <div> soup. For example, this document processor for processing documents doesn’t output paragraph tags (<p>…​</p>) - it outputs this instead: <div class="paragraph"><p>…​</p></div> - and it does something like that for basically everything. To be fair, they are aware of this & working on it.

So, I’m not going to use that, I’ll just use some community written back-end/converter that’s better…​ oh…​ yeah. Well, luckily, in this case there actually is one: html5s - which does a much better job.

Footnotes

AsciiDoc has built-in support for footnotes, but there are some rough edges:

The combination of these issues means that if you want externalized footnotes that work like the rest of your content, you have to give the footnote an ID and wrap the footnote definition in an inline pass-through. Because these become document attributes, you have to define them before you use them, so you should probably put these at the top.

This is more complex & convoluted than it needs to be - footnotes should just work. Anyway, it looks like this:

:fn-disclaimer: pass:q[footnote:disclaimer[Opinions are *my own*.]]

A bold statement!{fn-disclaimer}

Another bold statement!{fn-disclaimer}

They have a proposal for an improved footnote syntax - although it doesn’t talk about text formatting inside the footnote.

Blockquotes

I took me ages poking around on GitHub before I found out how to set the link text in the citation for a quoted block. This is the basic syntax:

[quote, attribution, citation title and information]
Quote or excerpt text

You can put a URL in there, and it works, but giving the URL a title doesn’t seem to work. So this works:

[quote, https://en.wikipedia.org/wiki/Main_Page]
Quote or excerpt text

but this doesn’t:

[quote, https://en.wikipedia.org/wiki/Main_Page[Wikipedia]]
Quote or excerpt text

However, using the Quoted paragraph syntax works:

"Quote or excerpt text"
-- https://en.wikipedia.org/wiki/Main_Page[Wikipedia]

Apparently, the correct way to do this with quoted blocks, is to “use single quotes around the attribute value, that gives Asciidoctor the hint to apply normal substitutions (just like paragraph text)”[2]. Not sure what that means at this point, but the docs on subtitutions are here. This is what it looks like in this case:

[quote, 'https://en.wikipedia.org/wiki/Main_Page[Wikipedia]']
Quote or excerpt text

Adding & removing plugins

The AsciiDoctor + htmls output has better figure output than reStructuredText + my Better Figures & Images Plugin, so I don’t need that anymore - provided that I convert all articles using figures to AsciiDoc. On the other hand, the extract_toc plugin doesn’t work for AsciiDoc + htmls output, so I copied it to a local plugin and modified it to work:

# -*- coding: utf-8 -*-
"""
Extract Table of Contents from AsciiDoc output from the htmls backend
========================

A Pelican plugin to extract table of contents (ToC) from `article.content` and
place it in its own `article.toc` variable for use in templates.
"""

from os import path
from bs4 import BeautifulSoup
from pelican import signals, readers, contents
import logging

logger = logging.getLogger(__name__)


def extract_asciidoc_toc(content):
    if isinstance(content, contents.Static):
        return

    soup = BeautifulSoup(content._content, "html.parser")
    toc = None

    toc = soup.find("nav", id="toc")

    if toc:
        toc.extract()
        content._content = soup.decode()

        # Remove: <h2 id="toc-title">Table of Contents</h2>
        toc.h2.decompose()

        # Change all ordered lists to unordered
        for l in toc("ol"):
            l.name = "ul"

        content.toc = toc.decode()

        logger.debug(f"ExtractAsciidocToc: content.toc: {content.toc}")


def register():
    signals.content_object_init.connect(extract_asciidoc_toc)

Converting your existing content to AsciiDoc

This depends on the format of your existing content:

$ pandoc --wrap=preserve -f rst -t asciidoctor "source.rst" > "dest.adoc"

#
# Pre-process
#
cat "$src_path" | \
# Remove :alt: tags from figures & images, otherwise they get lost
sed -r 's/:alt: /\n/g' | \
# Tabs to spaces
sed -r 's/\t/  /g' | \
#
# Convert rst to asciidoc using pandoc
#
pandoc --wrap=preserve --from rst --to asciidoctor | \
#
# Post-process
#
# Fix metadata syntax, from date:: to :date:
sed -r 'N; s/^(.*)::\n /:\1:/g; P; D' | \
# Remove extra breaks created from figure caption conversion
sed -r 'N; s/____\n//g; P; D' | \
# Fix Pelican {static} links
sed -e 's/%7B/{/g' -e 's/%7D/}/g' \
> "$src_folder/$src_name".adoc

$ git clone https://github.com/dflock/sphinx_asciidoc.git
$ cd sphinx_asciidoc
$ python3 -m venv ~/venv/sphinx_asciidoc
$ source ~/venv/sphinx_asciidoc/bin/activate
$ python3 -m pip install -r requirements.txt

$ python3 ./sphinx_asciidoc/writer.py source.rst

#
# Things that should be options, but aren't
#
# Output the rendered TOC from docutils, or just `:toc:`
self.outputTOC = False
# Table column alignment, if not specified. Can be <>^ or
# '' for unspecified.
self.defaultTableColAlign = ""
# Specify percentages for columns widths, or leave browser to auto-layout?
self.defaultTableColWidths = True
# Do you want to output the [1] ref's after the {footnote}, or let asciidoctor do it?
self.outputFootnoteRef = False

The AsciiDoc Specification

The first and biggest one is that AsciiDoc is finally getting a proper spec, under the umbrella of the Eclipse Foundation. This is something that Markdown never had until CommonMark - and that AsciiDoc has lacked up to now. What this means is:

Here is the AsciiDoc Language project proposal and the approved scope of the project.

So, this should help prevent the fragmentation that plagues the Markdown ecosystem, as well a making it easier for people to develop AsciiDoc parsers & tools. Still nowhere near as easy as implementing a Markdown one, though - AsciiDoc is just more complex.

Having said that, this is a big project and most of the activity is taking place on mailing lists - there also now a website for the Working Group which currently includes meeting minutes etc…​ There is now an AsciiDoc language repo for discussing the spec work, but it’s still early days: https://gitlab.eclipse.org/eclipse/asciidoc/asciidoc-lang/

libasciidoc

Libsciidoc is a Golang library for processing AsciiDoc files. This uses a PEG parser with a formal grammar for AsciiDoc. It already supports a useful subset of AsciiDoc and is being slowly worked on by a few people, I think with the intention to use it with Hugo, which will make a nice combination, when it’s done.

Like most software written in Go, it’s statically linked, which means no dependencies at all - you just need to put the libacsiidoc binary somewhere and run it. This is really nice compared to setting up and maintaining the Ruby dependencies required for Asciidoctor, or the JS & Java ones for Asciidoctor-J/Java, for example.

Footnotes & References: