How can I render HTML using Liquid in asciidoc in Jekyll?

Question

In my current Jekyll setup I am writing all my posts using the asciidoc (.adoc) file format, specifically I'm using these plugins

plugins:
  - jekyll-asciidoc
  - jekyll-redirect-from
  - jekyll-feed

I am in need to create a custom HTML component which I have added in component.html under the _includes folder, following the includes feature of Jekyll.

I am able at the moment to use Liquid in a Markdown file to render the HTML component by just using

{% include component.html %}

at any point in my posts, but I can't do the same with asciidoc files. I've taken a look at their documentation and I can't find a suitable way to make use of this Jekyll feature.

Is there a way to use Liquid in asciidoc?

Answer 1

After a little bit of research I've found a couple of things with which I was able to inject _includes HTML components in an asciidoc file.

The Jekyll way

jekyll-asciidoc has a special page attribute to enable Liquid preprocessing, you can find the docs at :page-liquid:

So, in order to enable Liquid preprocessing you just have to add this to the asciidoc post

:page-liquid:

With this, Jekyll is going to parse every Liquid statement in your file before actually passing it to the asciidoc generator.

The post needs another little change at this point, citing the docs:

If you’re using the Liquid include tag to include HTML into the AsciiDoc document, enclose it in a passthrough block.

++++
{% include file.html %}
++++

By default :page-liquid: will escape Liquid generated content, which is why you need to enclose the {% include ... %} statement in the asciidoc Passthrough construct ++++ that is going to inject raw HTML into the page itself.

In conclusion, this is what an example post should look like:

_includes/component.html

<p>Some sample text</p>

_posts/liquid-in-asciidoc.adoc

---
title: "HTML component in adoc
---
:page-liquid:

++++
{% include component.html %}
++++

AsciiDoc Way

It's also possible to accomplish this by creating an AsciiDoc Extension, for example I could create a block extension that recognises this syntax

[example_component]
--
Some text here
--

The ruby extension is going to be

require 'asciidoctor/extensions'

include Asciidoctor

Asciidoctor::Extensions.register do
  block :example_component do
    process do |parent, reader, attributes|
      content = reader.lines.join(' ')
      html = %(<p>#{content}</p>)
      create_pass_block parent, html, {}, :content_model => :raw
    end
  end
end

This is going to produce the same result as above