This post documents some of the quirks involved in setting up a weblog that uses both Markdown and AsciiDoc.

Why AsciiDoc?

AsciiDoc is a capable text format for authoring technical documentation — it offers many features that allow text to be marked up with greater precision than when written using Markdown.

This site used to be built using the Hugo static website generator previously. Although Hugo is very capable at handling content written in Markdown, it needs to invoke an external program to process content in the AsciiDoc format.

The canonical tool for translating AsciiDoc to HTML is a Ruby-based program named AsciiDoctor.[1] However, getting Hugo and Asciidoctor to work well together turned out to be tricky.

I ended up migrating the site to use the Ruby-based Jekyll static site generator instead of Hugo. I could then use the Jekyll AsciiDoc plugin for translating AsciiDoc content.

Migration Steps

The main steps needed for the migration were:

  1. Changing the Hugo-isms in existing Markdown content to their Jekyll equivalents.

  2. Aligning CSS stylesheets.

Changing Hugo-isms To Jekyll-isms

Custom Shortcodes

Hugo has the notion of a “shortcode”, which is special syntax that expands to HTML when used. Hugo allows users to implement their own shortcodes.

Jekyll does not have shortcodes, but it instead has “includes” that support parameters. This Jekyll feature sufficed to implement equivalents for the custom Hugo shortcodes that I had used for my site.

For example:

Hugo Jekyll 
{{< googleslides src="..." >}}
 
{% include googleslides.html src="..." %}

Here the Jekyll inclusion of googleslides.html expands to the same HTML that the custom Hugo googleslides shortcode expands to.

Translating Hugo’s {{< figure ... }}

Hugo’s figure shortcode wraps its content in an HTML <figure> element.

I used a third-party Ruby gem named “jekyll-figure” for migrating from Hugo to Jekyll. This Ruby gem implements a Jekyll “tag”, also named figure, that works in a fashion similar to Hugo’s figure shortcode.

Hugo Jekyll 
{{< figure src="/path/to/img" >}}
 
{% figure %}
{:style="text-align:center;"}
![AltText](/path/to/img)
{% endfigure %}
Note
 The {:style=...} construct in the Jekyll code above centers the figure. Hugo’s figure shortcode centers figures by default, but the Jekyll plugin does not.

Translating Hugo’s {{< relref ... }}

The uses of Hugo’s builtin relref shortcode were replaced by equivalent uses of Jekyll’s relative_url filter.

Path Differences

Hugo and Jekyll place the HTML files that they generate in differing locations in the built site. These locations were however easy to align in configuration (file: _config.yml for Jekyll), or adjusted for in the migrated text files using Jekyll’s permalink feature.

CSS Adjustments

I used the default Minima theme as the ‘base’ theme for the migrated site. This theme comes with its own set of CSS rules.

However, the HTML produced by the Jekyll AsciiDoc plugin expects its own set of CSS rules to be present (see asciidoctor.css from the Jekyll AsciiDoc Quickstart project).

These two CSS rule sets are not compatible. I ended up tweaking the CSS in the two rulesets to make the rendered AsciiDoc and Markdown content look "similar enough".

The styling of this site definitely needs further work.

Future Work

Generate Cleaner HTML

The html5 backend to Jekyll AsciiDoc currently generates ‘noisy’ HTML, with many redundant <div> elements. For example, every paragraph in AsciiDoc source is wrapped in a redundant <div> element:

Table 1. Too many <div> elements in Jekyll’s output

Asciidoc

 
I am a paragraph.

HTML output

 
<div class="paragraph">
<p>I am a paragraph</p>
</div>

There appears to be a plugin for Jekyll that generates ‘semantic’ HTML on Github: asciidoctor-html5s. However, the HTML code that this plugin generates seems to be incompatible with the asciidoctor.css CSS ruleset.

Crafting a suitable set of CSS rules and then using this plugin could perhaps be a future project.

Use A Responsive Jekyll Theme

A ‘responsive’ theme should make this site easier to view on mobile devices.

I may attempt a change of theme after I learn how CSS (‘responsive’ CSS in particular) works. 😎

Conclusion

The site has been migrated. Its content is currently a mix of Markdown and AsciiDoc, with the two blending together reasonably well.

I look forward to getting on with writing documentation in AsciiDoc.

1. There are efforts underway to standardize AsciiDoc syntax to permit more tools to process it; please see: The AsciiDoc Working Group, https://asciidoc-wg.eclipse.org/.