Asciidoc Breaks with Shortcodes

[stiobhart]

I was toying with the idea of converting my site’s content files to use asciidoc rather than markdown, as I’m using the former more often and the latter less often these days.

Anyway, I converted a couple of existing markdown pages without incident, until I came to one which uses the {{figure}} shortcode. When I convert that page to asciidoc and Hugo rebuilds the site, the content of the shortcode is rendered directly to the page, rather than being replaced with HTML generated by the shortcode. Any idea why this is?

BTW - I used https://github.com/asciidoctor/kramdown-asciidoc to convert the page in question from markdown to asciidoc.

Here is the the original markdown version of the page:

And here is the asciidoc conversion:

Excepting the different URL syntax, they look pretty identical to me. But, while the markdown version built by Hugo renders the image correctly, here’s what I get with the asciidoc version:

And in the source code. As you can see, the actual shortcode code is rendered inside a paragraph tag, within quotes,rather than being replaced by HTML:

For comparison, the same page rendered from the markdown file:

And, just for completeness, here’s the {{figure}} shortcode:

{{ "<!-- begin image shortcode //-->" | safeHTML }}
<figure {{ with .Get "class" }}class="{{.}}"{{ end }}>{{ with .Get "link"}}<a href="{{.}}">{{ end }}<img src="{{ .Get "src" }}" {{ if or (.Get "alt") (.Get "caption") }}alt="{{ with .Get "alt"}}{{.}}{{else}}{{ .Get "caption" }}{{ end }}"{{ end }} />{{ if .Get "link"}}</a>{{ end }}{{ if or (or (.Get "title") (.Get "caption")) (.Get "attr")}}<figcaption>{{ if isset .Params "title" }}{{ .Get "title" }}{{ end }}{{ if or (.Get "caption") (.Get "attr")}}{{ .Get "caption" }}{{ with .Get "attrlink"}}<a href="{{.}}"> {{ end }}{{ .Get "attr" }}{{ if .Get "attrlink"}}</a> {{ end }}{{ end }}
</figcaption>{{ end }}</figure>
{{ "<!-- end image shortcode //-->" | safeHTML }}

[stiobhart]

I’ll answer my own question here, as I tracked down the problem.

The issue is with how the Hugo passes Asciidoc page content straight to an external parser, rather than pre-porcessing it first. So we need to tell the external Asciidoc parser to passthrough the Hugo shortcodes unmodified. From the Asciidoc Syntax Guide

++++
<p>
Content in a passthrough block is passed to the output unprocessed.
That means you can include raw HTML, like this embedded Gist:
</p>

<script src="https://gist.github.com/mojavelinux/5333524.js">
</script>
++++

So, in the case of Hugo shortcodes, it was simply a case of adding those ++++ passthrough fence-blocks to the shortcode. So that:

{{ "<!-- begin image shortcode //-->" | safeHTML }}
<figure {{ with .Get "class" }}class="{{.}}"{{ end }}>{{ with .Get "link"}}<a href="{{.}}">{{ end }}<img src="{{ .Get "src" }}" {{ if or (.Get "alt") (.Get "caption") }}alt="{{ with .Get "alt"}}{{.}}{{else}}{{ .Get "caption" }}{{ end }}"{{ end }} />{{ if .Get "link"}}</a>{{ end }}{{ if or (or (.Get "title") (.Get "caption")) (.Get "attr")}}<figcaption>{{ if isset .Params "title" }}{{ .Get "title" }}{{ end }}{{ if or (.Get "caption") (.Get "attr")}}{{ .Get "caption" }}{{ with .Get "attrlink"}}<a href="{{.}}"> {{ end }}{{ .Get "attr" }}{{ if .Get "attrlink"}}</a> {{ end }}{{ end }}
</figcaption>{{ end }}</figure>
{{ "<!-- end image shortcode //-->" | safeHTML }}

Becomes:

++++
{{ "<!-- begin image shortcode //-->" | safeHTML }}
<figure {{ with .Get "class" }}class="{{.}}"{{ end }}>{{ with .Get "link"}}<a href="{{.}}">{{ end }}<img src="{{ .Get "src" }}" {{ if or (.Get "alt") (.Get "caption") }}alt="{{ with .Get "alt"}}{{.}}{{else}}{{ .Get "caption" }}{{ end }}"{{ end }} />{{ if .Get "link"}}</a>{{ end }}{{ if or (or (.Get "title") (.Get "caption")) (.Get "attr")}}<figcaption>{{ if isset .Params "title" }}{{ .Get "title" }}{{ end }}{{ if or (.Get "caption") (.Get "attr")}}{{ .Get "caption" }}{{ with .Get "attrlink"}}<a href="{{.}}"> {{ end }}{{ .Get "attr" }}{{ if .Get "attrlink"}}</a> {{ end }}{{ end }}
</figcaption>{{ end }}</figure>
{{ "<!-- end image shortcode //-->" | safeHTML }}
++++

Then they work properly.

I thought I was away there. But, unfortunately I’ve now run into another [seemingly insurmountable] problem, which will merit its own post!