How to escape Liquid tags
Summary
Escaping Liquid tags can be hell. In this article I will explain 4 ways you can escape Liquid tags to display them as text instead of executing them: {% raw %} and {% endraw %}, string interpolation, and HTML entities.
Introduction #
When working with Liquid, the templating language used in platforms like Shopify and Jekyll, you may encounter situations where you need to display Liquid syntax as text rather than executing it, like me on this page.
This article explains several ways to escape Liquid tags effectively. Since there are different implementations of Liquid, some of the solutions might not work for you. That is why I am showing 4 different ones here.
This website runs on Jekyll. To write the article, I was forced to use two of the options to escape {% raw %} and {% endraw %}. This is still ugly in Jekyll.
Use raw and endraw #
One of the simplest ways to escape Liquid tags is by using the {% raw %} and {% endraw %} tags. These tags prevent Liquid from processing anything inside them.
{% raw %}{{ user.name }}{% endraw %}
If you type {% raw %}{{ user.name }}{% endraw %}, Liquid does not render {{ user.name }} as a variable but instead displays it as plain text.
String interpolation for tag markup #
If you need to escape a Liquid tag, you can use string interpolation to construct the tag dynamically. This method ensures that Liquid does not interpret the tag.
{{ "{{ "{% assign variable = 'test' %}" }}
This outputs {% assign variable = 'test' %} as text rather than executing the assignment.
String interpolation is the process of embedding expressions or variables within a string. In Liquid, this can be used to construct syntax dynamically, preventing unwanted interpretation.
String interpolation for output markup #
For escaping output markup, a similar technique applies. You can dynamically construct the double curly braces to prevent Liquid from processing them.
{{ "{{ user.name }}" }}
This results in {{ user.name }} being displayed as text instead of rendering the variable.
Use HTML entities #
Another way to escape Liquid syntax is by replacing { and } with their corresponding Hypertext Markup Language (HTML) entities:
{{ user.name }}
This ensures that the template displays {{ user.name }} as plain text instead of interpreting it as Liquid syntax. Of course, this option only works outside of HTML code elements, as they prevent the interpretation of the entities.
If correct code formatting is important to you, this solution is only suitable in an absolute emergency.
Disable Liquid in Jekyll #
Since Jekyll 4.0, you can add render_with_liquid: false in your front matter to disable Liquid entirely for a particular document.
---
render_with_liquid: false
---
This prevents Liquid from processing the file, allowing you to include Liquid syntax without escaping it. Maybe not ideal, but still a valid option.
Happy hacking.
Further readings #
Sources and recommended, further resources on the topic:
Author
Jonas Jared Jacek (J15k)
Jonas works as project manager, web designer, and web developer since 2001. On top of that, he is a Linux system administrator with a broad interest in things related to programming, architecture, and design. See: https://www.j15k.com/License
How to escape Liquid tags by Jonas Jared Jacek is licensed under CC BY-SA 4.0.
This license requires that reusers give credit to the creator. It allows reusers to distribute, remix, adapt, and build upon the material in any medium or format, for noncommercial purposes only. To give credit, provide a link back to the original source, the author, and the license e.g. like this:
<p xmlns:cc="http://creativecommons.org/ns#" xmlns:dct="http://purl.org/dc/terms/"><a property="dct:title" rel="cc:attributionURL" href="https://www.ditig.com/how-to-escape-liquid-tags">How to escape Liquid tags</a> by <a rel="cc:attributionURL dct:creator" property="cc:attributionName" href="https://www.j15k.com/">Jonas Jared Jacek</a> is licensed under <a href="https://creativecommons.org/licenses/by-sa/4.0/" target="_blank" rel="license noopener noreferrer">CC BY-SA 4.0</a>.</p>For more information see the Ditig legal page.
