How to write code documentation in Liquid?
I have been writing a lot of Liquid code for clients, and as the complexity of this code increases, I find it beneficial to include some form of documentation. However, I have found that there isn't much available in terms of built-in documentation systems for Liquid. I appreciate tools like JSDoc, for instance, but unfortunately, Liquid lacks a dedicated built-in documentation system.
Nonetheless, I aim to follow certain rules when working with Liquid.
In Liquid, you can include code blocks and provide parameters within these blocks.
When using render or include Liquid Documentation I like write something like this:
{#-
This is a Liquid code block that does something important.
Parameters:
- param_1: String
- param_2: Object with property.
-#}
{% include 'path/to/file',
param_1: 'my value',
param_2: object.property %}
This example is relatively straightforward, but when dealing with a complex code blocks, it can be highly beneficial to document its functionality and the expected parameters it requires.
Liquid involves verbose coding, so when working on more intricate tasks, I make an effort to provide explanations for individual lines of code through comments.
Example with inline comment.
<div class="simple-menu">
{% if simple_menu.title != blank %}
{%- comment -%}
If title contains [empty] we replace it, as to render the h2 but nothing in it...
{%- endcomment -%}
<h4 {% if simple_menu.title contains '[empty]' %}class="empty"{% endif %}>
{{ simple_menu.title | replace: '[empty]', '<span class="filler" aria-hidden="true">empty</span>' }}
</h4>
{% endif %}
{%- for simple_link in simple_menu.menu_items -%}
{% include 'includes/modules/simple_link' %}
{%- endfor -%}
</div>This is a weird example, but the design was that if the title was empty, we would render the h2 but with a span in it that would be hidden for screen readers. This is because we wanted to keep the same layout, but not have the title visible.
Alas, if you have any tips or ideas about writing understandable liquid code, let me know on twitter or github!