Liquid Coding Guide

Our template-parsing engine of choice is Liquid, and that means coding in the Liquid templating language, which can be frustrating and awkward.

Templating

First, let’s talk about what Liquid is and does.

Liquid is not quite a programming language, which is by design. While the syntax can be used to transform text objects, Liquid offers no complete environment for building applications nor for acting on, say, the filesystem in any real way.

By design, Liquid is intended to perform the job of transforming text, which it handles very well. The whole point is to empower a user role that can be given the tools to transform text inside other applications, with the complicated or hazardous or contextual aspects abstracted out by developers of that application.

Liquid is for non-programmers, which comes at a cost for programmers. Liquid can be very frustrating to troubleshoot, and Liquid lacks debugging and testing tools of more-robust programming languages. Liquid has seen the test of time and broad implementation, but for some reason it has not accrued an active community.

Liquid is a tag-based markup format, meaning its programmatic elements are wrapped in {% tags %}, as it were, which are intermingled with text. Whatever is not wrapped in tags is plaintext the parser will leave untouched.

Whitespace Control

Like pretty much all template parsers, Liquid has a tendency to leave large blocks of whitespace behind where your tags

Liquid-only Partials

While most partials are used to generate HTML, others can process data into new objects to be passed on to their caller. This lets you create “functions” of a sort for repeated procedures.

Whatever happens inside these partials gets passed on to the lines that follow in the calling file. Used inside a for loop, these can be pretty powerful ways of keeping the parent-file code tidy.

Templating HTML

Liquid was designed for HTML, and its primary use in a Jekyll platform is generating HTML in theme layouts and include partials.

Whitespace control tends to be relatively unimportant for HTML templates. Modern browsers are incredibly tolerant of whitespace in HTML, and for most applications, the templates themselves are the primary way you will work with the HTML outside the browser.

Modest amounts of whitespace can even be helpful in debugging directly in your built files. You might appreciate it when you find yourself spelunking through your _site/ directory to see what your templates are actually generating during a build.

Nevertheless, I would say more often, you should find yourself using your browser’s Developer Tools.

Code Nesting

So I would suggest saving all the whitespace-control for non-HTML templating.

Instead, the thing to pay attention to for HTML templating is the accordion your code forms. Both HTML and Liquid look better to the human eye and are much easier to debug with consistent nesting.

Mixed, nested Liquid/HTML from _includes/nav-subject-menu.html
include::{path_to_jekyll_includes}/nav-subject-menu.html

The key to mixed nesting is to pick whether to nest the two languages together or separately.

Independently nested Liquid/HTML (dummy code)
<ul>
{% for link in site.data.navs %}
  {% if link.kids %}
  <li>
    <a href="{{ link.href | default: '#' }}">
      {{ link.text }}</a>
    {% for kid in link.kids %}
      <a href="{{ kid.href }}">
        {{ kid.text }}
      </a>
    {% endfor %}
    </div>
  </li>
  {% else %}
  <li>
    <a href="{{ link.href }}">
      {{ link.text}}
    </a>
  </li>
  {% endif %}
{% endfor %}
</ul>
Synchronously nested Liquid/HTML (dummy code)
<ul>
  {% for link in site.data.navs %}
    {% if link.kids %}
      <li>
        <a href="{{ link.href | default: '#' }}">
          {{ link.text }}
        </a>
        {% for kid in link.kids %}
          <a href="{{ kid.href }}">
            {{ kid.text }}
          </a>
        {% endfor %}
        </div>
      </li>
      {% else %}
      <li>
        <a href="{{ link.href }}">
          {{ link.text}}
        </a>
      </li>
    {% endif %}
  {% endfor %}
</ul>

The main drawback of synchronous nesting is that with deep nesting the lines get long and wrap in the editor window. The rest of the decision comes down to which looks better to your eye.

The AsciiDocsy site nests independently.

Templating YAML

TODO: Coming soon, sourced in LiquiDoc Ops User Guides.

Templating AsciiDoc

TODO: Coming soon, sourced in LiquiDoc Ops User Guides.

Feedback, please.