Liquid tags and shortcodes

by Gene — posted on 5 April 2022

Shortcodes can be used to process rendered content or as a handy way to output reusable fragments of content, and even web components, without having to deal with HTML or JavaScript.

Web starter shortcodes

layout

This tag outputs a div with the given Flex Layout Attributes. It's mainly intended wrap and format zx shortcode output.

{% layout '<flex_layout_attributes>' ['<element_attr_1>' ... '<element_attr_n>'] %}
    (content)
{% endlayout %}

Example:

{% layout 'row center-center' 'style="gap: 12px"' %}
    {% zx 'button' '#test-link-1' %} Button 1 {% endzx %}
    {% zx 'button' '#test-link-2' %} Button 2 {% endzx %}
{% endlayout %}

Button 1 Button 2

zx

The zx shortcode is used to render HTML fragments or components based on user-defined tag templates. Tag templates are loaded from the ./templates/tags folder, and they consist of simple and small JavaScript code that usually renders reusable bits.

{% zx '<tag_name>' ['<tag_option_1>' ... <tag_option_n>] %}
(optional content / configuration)
{% endzx %}

In the previous example the tag button is loaded from ./templates/tags/button.js. The first option for this button tag is the anchor name or URL to be opened when the button is clicked (#test-link-1 in this case).

For more zx tags examples see also:

Adding custom zx tags

A custom tag can be implemented by adding a <custom_tag_name>.js file to the ./templates/tags/ folder.
For instance, the following code is the ./templates/tags/button.js used in the previous example:

const template = `<a class="button" href="{{ linkUrl | safe }}">
  {{ content }}
</a>`;

module.exports = (render, content, linkUrl) => {
  return render(template, {content, linkUrl});
};

rawFile

This tag can be used to include normalized HTML fragments inside .md files without further processing from Markdown engine.

{% rawFile "<file_path>" %}

unpre

Sometimes can happen to use HTML code in a Markdown .md file, and this tag can be used to wrap the HTML code inside a preformatted block, so that it will be actually recognized as HTML and the editor will highlight the code correctly. It's just an aesthetic hack to make your eyes happier if the editor is not highlighting the HTML markup.

Example:

{% unpre %}
'''html
<div style="color: purple">Hello World!</div>
'''
{% endunpre %}

wrapDom / wrapCss

These two tags will add to a CSS and HTML fragments, the required code so that the CSS will be only applied to those HTML fragments defined inside wrapDom having the same <fragment_id> (scoped CSS).
This can also be used with the include shortcode, to load the CSS and HTML fragments from external files.

Syntax:

{% wrapDom '<fragment_id>' %}
  <!-- HTML fragment -->
{% endwrapDom %}
<style>
{% wrapCss '<fragment_id>' [<encapsulate>] %}
  /* CSS fragment */
{% endwrapCss %}
</style>

Example:

<h3>Global scope H3</h3>

{% wrapDom 'test-fragment' %}
<div>
    <h3>Fragment scope H3</h3>
</div>
{% endwrapDom %}

<style>
{% wrapCss 'test-fragment' %}
:host {
    text-align: center;
}
h3 {
    color: deeppink;
}
{% endwrapCss %}
</style>