Liquid — Safe Customer-Facing Template Language by Shopify

Introduction

Liquid is an open-source template language created by Shopify and written in Ruby. It was designed from the ground up to be safe for untrusted user input, making it the standard choice for platforms that let end users edit templates without risking code execution on the server.

What Liquid Does

• Renders dynamic content using objects ({{ }}), tags ({% %}), and filters
• Sandboxes template execution so users cannot access the host environment
• Provides built-in filters for string manipulation, math, date formatting, and array operations
• Supports control flow with if/else, for loops, case/when, and unless blocks
• Powers Shopify themes, Jekyll static sites, and many SaaS platforms

Architecture Overview

Liquid operates in two phases: parsing and rendering. The parser tokenizes a template string into a tree of Tag and Variable nodes, which is then cached. At render time, the engine walks the tree, resolves variables against a provided context (called assigns), applies filters, and streams output. The strict separation between parsing and rendering ensures that user-supplied templates cannot execute arbitrary Ruby code.

Self-Hosting and Configuration

• Install via gem install liquid or add gem 'liquid' to your Gemfile
• Parse templates once with Liquid::Template.parse(source) and render with different contexts
• Register custom tags by subclassing Liquid::Tag and calling Liquid::Template.register_tag
• Register custom filters as Ruby modules and include them during rendering
• Use strict mode with Liquid::Template.error_mode = :strict to surface undefined variables

Key Features

• Security-first design prevents file system access, eval, or method calls from templates
• Deterministic rendering makes output reproducible and cacheable
• Portable: implementations exist in Ruby, Python, JavaScript, Go, PHP, Java, and Rust
• Incremental rendering support for streaming large templates
• Well-documented with a stable API that has changed little over a decade

Comparison with Similar Tools

• Jinja2 — Python template engine with more powerful expressions; allows arbitrary method calls unless sandboxed manually
• Handlebars — JavaScript logic-less templates; less expressive filters but similarly safe
• ERB — Ruby embedded templates with full Ruby access; not safe for user-supplied content
• Twig — PHP template engine inspired by Jinja2; offers sandboxing but it is opt-in rather than default

FAQ

Q: Is Liquid only for Ruby projects? A: No. Community ports exist for JavaScript (liquidjs), Python (python-liquid), Go, PHP, and more. The syntax is language-agnostic.

Q: Can users break out of the sandbox? A: By design, no. Liquid templates cannot call Ruby methods, access the file system, or modify server state.

Q: How do I add a custom filter? A: Define a Ruby module with methods matching filter names and pass it as a filter option when rendering.

Q: Does Liquid support template inheritance? A: Not natively in the core library, but Jekyll and Shopify add layout and section systems on top of Liquid.

Sources

• https://github.com/Shopify/liquid
• https://shopify.github.io/liquid/