Utilizing AsciiDoc & Asciidoctor for running a blog · duncan­lock­.web

Enhancing expertise isn’t as good

Most fashionable editors help AsciiDoc syntax highlighting and generally preview, through plugins. However, as anticipated, these aren’t as well-developed, quite a few or as totally featured because the Markdown equivalents. If you happen to’re utilizing the Asciidoctor markdown-a-like syntax for the straightforward stuff, then you possibly can simply inform the editor it’s Markdown, and use the extra totally featured markdown help.

Not a lot native help

If you happen to’re utilizing a Ruby weblog engine, it would possibly have native AsciiDoc support, or your weblog engine might need a plugin that helps it. Don’t count on each weblog engine to help it, although. Some weblog engines have an escape hatch that allow you to use Pandoc or another customized command to course of your content material – and whereas Pandoc does have AsciiDoc help, it’s neither full nor flawless.

Does native help matter?

Does the truth that the doc processing is shelled out to a black field truly have an effect on utilizing AsciiDoc for running a blog? Properly, it makes publishing a bit slower to quite a bit slower, relying on the dimensions of your web site. However in most weblog/publishing methods you’ve a template that defines the construction of the web page with some form of placeholder that claims {{content-goes-here}}. It doesn’t actually matter how the content material is generated, so long as it’s – and so long as the HTML that’s produced strains up along with your CSS & is cheap. Talking of which…​

Asciidoctor’s built-in HTML output might be higher

When asciidoctor processes your .adoc file you possibly can inform it what converter (or “back-end”) you need to use – i.e. what sort of output you need. These are the built-in options. That is what they are saying in regards to the default HTML converter:

That is technically true, nonetheless, whereas the HTML it produces is technically HTML5, it’s additionally <div> soup. For instance, this doc processor for processing paperwork doesn’t output paragraph tags (<p>…​</p>) – it outputs this as a substitute: <div class="paragraph"><p>…​</p></div> – and it does one thing like that for mainly every thing. To be honest, they are aware of this & working on it.

So, I’m not going to make use of that, I’ll simply use some group written back-end/converter that’s higher…​ oh…​ yeah. Properly, fortunately, on this case there truly is one: html5s – which does a a lot higher job.

AsciiDoc has built-in support for footnotes, however there are some tough edges:

The mix of those points signifies that if you need externalized footnotes that work like the remainder of your content material, it’s important to give the footnote an ID and wrap the footnote definition in an inline pass-through. As a result of these grow to be doc attributes, it’s important to outline them earlier than you utilize them, so it’s best to in all probability put these on the high.

That is extra advanced & convoluted than it must be – footnotes ought to simply work. Anyway, it appears to be like like this:

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

A daring assertion!{fn-disclaimer}

One other daring assertion!{fn-disclaimer}

They’ve a proposal for an improved footnote syntax – though it doesn’t speak about textual content formatting contained in the footnote.

Blockquotes

I took me ages poking round on GitHub earlier than I discovered the best way to set the hyperlink textual content within the quotation for a quoted block. That is the fundamental syntax:

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

You’ll be able to put a URL in there, and it really works, however giving the URL a title doesn’t appear to work. So this works:

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

however this doesn’t:

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

Nevertheless, utilizing the Quoted paragraph syntax works:

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

Apparently, the correct way to do this with quoted blocks, is to “use single quotes across the attribute worth, that offers Asciidoctor the trace to use regular substitutions (identical to paragraph textual content)”. Unsure what which means at this level, however the docs on subtitutions are here. That is what it appears to be like like on this case:

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

Including & eradicating plugins

The AsciiDoctor + htmls output has higher determine output than reStructuredText + my Higher Figures & Photographs Plugin, so I don’t want that anymore – supplied that I convert all articles utilizing figures to AsciiDoc. Then again, the extract_toc plugin doesn’t work for AsciiDoc + htmls output, so I copied it to an area plugin and modified it to work:

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

A Pelican plugin to extract desk of contents (ToC) from `article.content material` and
place it in its personal `article.toc` variable to be used in templates.
"""

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

logger = logging.getLogger(__name__)


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

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

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

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

        # Take away: <h2 id="toc-title">Desk of Contents</h2>
        toc.h2.decompose()

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

        content material.toc = toc.decode()

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


def register():
    indicators.content_object_init.join(extract_asciidoc_toc)

Changing your present content material to AsciiDoc

This is determined by the format of your present content material:

Changing reStructuredText to AsciiDoc

I attempted tons of various means of changing reStructuredText to AsciiDoc – and none of them are good.

Pandoc does a cheap job, except you utilize figures, which get fairly mangled. They’re aware/working on this. If you wish to use pandoc, That is the fundamental command:

See Also

Searching for the final saola

$ pandoc --wrap=protect -f rst -t asciidoctor "supply.rst" > "dest.adoc"

In addition to figures, this additionally messes up metadata and pelican {static} hyperlinks, so that you in all probability need some pre- & post-processing to repair that. I wrote a bit of shell script to repair every thing besides the figures:

#
# Pre-process
#
cat "$src_path" | 
# Take away :alt: tags from figures & photographs, in any other case they get misplaced
sed -r 's/:alt: /n/g' | 
# Tabs to areas
sed -r 's/t/  /g' | 
#
# Convert rst to asciidoc utilizing pandoc
#
pandoc --wrap=protect --from rst --to asciidoctor | 
#
# Publish-process
#
# Repair metadata syntax, from date:: to :date:
sed -r 'N; s/^(.*)::n /:1:/g; P; D' | 
# Take away additional breaks created from determine caption conversion
sed -r 'N; s/____n//g; P; D' | 
# Repair Pelican {static} hyperlinks
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
$ supply ~/venv/sphinx_asciidoc/bin/activate
$ python3 -m pip set up -r necessities.txt

$ python3 ./sphinx_asciidoc/author.py supply.rst

#
# Issues that ought to be choices, however aren't
#
# Output the rendered TOC from docutils, or simply `:toc:`
self.outputTOC = False
# Desk column alignment, if not specified. May be <>^ or
# '' for unspecified.
self.defaultTableColAlign = ""
# Specify percentages for columns widths, or depart browser to auto-layout?
self.defaultTableColWidths = True
# Do you need to output the [1] ref's after the {footnote}, or let asciidoctor do it?
self.outputFootnoteRef = False

The AsciiDoc Specification

The primary and largest one is that AsciiDoc is finally getting a proper spec, beneath the umbrella of the Eclipse Basis. That is one thing that Markdown by no means had till CommonMark – and that AsciiDoc has lacked so far. What this implies is:

Right here is the AsciiDoc Language project proposal and the approved scope of the project.

So, this could assist forestall the fragmentation that plagues the Markdown ecosystem, as nicely a making it simpler for folks to develop AsciiDoc parsers & instruments. Nonetheless nowhere close to as straightforward as implementing a Markdown one, although – AsciiDoc is simply extra advanced.

Having mentioned that, this can be a massive mission and many of the exercise is happening on mailing lists – there additionally now a website for the Working Group which presently contains assembly minutes and so on…​ There’s now an AsciiDoc language repo for discussing the spec work, nevertheless it’s nonetheless early days: https://gitlab.eclipse.org/eclipse/asciidoc/asciidoc-lang/

libasciidoc

Libsciidoc is a Golang library for processing AsciiDoc files. This makes use of a PEG parser with a proper grammar for AsciiDoc. It already helps a helpful subset of AsciiDoc and is being slowly labored on by a number of folks, I believe with the intention to make use of it with Hugo, which is able to make a pleasant mixture, when it’s carried out.

Like most software program written in Go, it’s statically linked, which implies no dependencies in any respect – you simply must put the libacsiidoc binary someplace and run it. That is very nice in comparison with establishing and sustaining the Ruby dependencies required for Asciidoctor, or the JS & Java ones for Asciidoctor-J/Java, for instance.