Recently, we’ve updated the platformOS documentation with a complete guide to Liquid Markup, including an introduction, types, tags, filters, whitespace control, and detailed descriptions of platformOS-specific filters and tags — all of them demonstrated with examples.

Why Liquid?

When building platformOS, an API-driven, model-based application development platform, we needed a way to render layouts and data without the need for access to underlying backend technologies — that meant we had to use a templating language.

We decided to go with Liquid, because:

• Liquid markup is one of the simplest markups out there. 

• It has built-in support for performance profiling.

• The logic has been kept simple on purpose — it’s small, yet effective. 

• The filters syntax is very elegant.

• It’s easily extensible. 

• It’s very popular. You can find Liquid implementations in most languages, with some of the biggest brands using it. 

• Liquid syntax highlighting is widespread in editors. 

• It’s proven scalability since it’s been invented and open-sourced by Shopify.


A complete guide to Liquid

Many of our Partners noticed that if they want to learn Liquid, they have to jump between the official Liquid documentation and our docs to get the complete overview. We also noticed missing parts and holes in some of the docs, so to help our Partners and all learners of Liquid, we decided to create a compilation of the best parts of all sources to offer a single, comprehensive guide.

Knowledge about Liquid is scattered through many resources. Some of them are better in some parts, some of them have unique parts (for example, mentions of the with and for arguments for the include tag), some have better examples for filters.

Here’s a list of resources we used:

• https://shopify.github.io/liquid: The official Liquid documentation. We reused the descriptions of filters and some tags from here, as they had the best examples. The explanations of types and truthiness were also very helpful. 

• https://help.shopify.com/en/themes/liquid: Liquid reference on the official Shopify website, creators of the Liquid templating language. They also provide custom filters and tags. We found that the explanation of objects (forloop, tablerowloop) was very good here.  

• https://www.rubydoc.info/gems/liquid/4.0.1/Liquid: Ruby Liquid gem. We first encountered mentions of with and for parameters for the include tag here. This is the ultimate source of truth but it’s aimed at people comfortable with Ruby source code.

• https://github.com/shopify/liquid/wiki/Liquid-for-Designers: Liquid for Designers is an attempt to create a summary, or cheat sheet, for people that already know Liquid but need quick access to the most important parts from time to time. 


How to use our docs

Inspired by the official documentation, we divided our Liquid documentation into multiple parts for easy access, keeping it logical for newcomers. We started with an introduction, then described types, tags grouped into three larger sections (variables, flow control, and loops), filters, objects, and whitespace control.

At the bottom of the menu, we included platformOS-specific tags and filters. You should start learning about these when you’re comfortable with Liquid in general. We added a lot of custom filters and tags that make dealing with Liquid, dates, JSON, data structures, encoding, or URL templates easier. platformOS gives you the power to improve your code by exposing the Liquid profiler and giving you a filter that measures the execution time of any given block with a 1ms granularity.

Because pages can be long with a lot of filters on them, we are planning to implement a table of contents to help orientation and navigation. If you have any suggestions for improvements or would like to extend our docs, please contribute to our documentation on GitHub.

We hope to provide docs that you can use as a newcomer to quickly learn Liquid basics and start developing on platformOS using our custom filters and tags.