Liquid ‘raw’ Tag and Fenced Code Blocks
Liquid is a template engine used by Jekyll. Jekyll supports all standard Liquid Tags and Filters and adds some filters and tags for common tasks. Tags are used for template logic processing. Filters are output filters that allows text to be transformed before sending it to the output. For more information on Tags and Filters, go to Liquid for Designers.
Liquid Output markup is surrounded by double curly braces. Tag markup is surrounded by a curly brace and a percent sign.
{{ output }}
{% tag %}Tag Markup raw and endraw
The purpose of the raw and endraw tag markup is to allow anything in between to be displayed as is.
Meaning anything in between those tags will be ignored by the templating system.
From the Liquid wiki it says:
Raw temporarily disables tag processing. This is useful for generating content (eg, Mustache, Handlebars) which uses conflicting syntax.
One can use the {% raw %} and {% endraw %} tag markups in code blocks.
This Liquid templating engine issue is tricky on the raw and endraw tag markup.
If we want to display a raw tag markup like {% raw %}, we cannot just type it as is.
The templating engine will interpret it as the beginning of the raw tag markup and will not be displayed.
Using a Variable
We can display {% raw %} by wrapping it between a raw and endraw tag markup like this:
{% raw %} {% raw %} {% endraw %}One way to do this is to use a variable whose value is the opening tag markup characters {%.
(How we declare the variable is shown below)
The variable will be used instead of the characters {% in {% endraw %}.
The code should look like:
{% assign openTag = '{%' %}
...
{% raw %} {% raw %} {{ openTag }} endraw %}The openTag output tag markup will be replaced by the characters {%.
The code above will display {% raw %}. It may be a bit confusing at first but works pretty well.
Using an HTML Entity
Another way of doing it is to use part of the tag as an HTML entity.
Liquid will not recognize it as part of the tag and the browser will convert the HTML entity and display it.
We can convert the opening curly brace as an HTML entity { and the browser will display it as {.
We can display {% raw %} by replacing the opening curly brace with the HTML entity { and copy the rest.
<code>{% raw %}</code>Raw Fenced Code Block Syntax
How do I show the reader the code on how to display a fenced code block with syntax highlighting using {% raw %} and {% endraw %}?
That means how it would appear on screen before any rendering or transformation of the code occurs.
This is akin to the ‘view as Raw’ feature in GitHub source code display.
I will repeat it here, the purpose of the raw and endraw tag markup is to allow anything in between to be displayed as is.
Meaning anything in between those tags will be ignored by the templating system.
Here is a hack version of what I want to show. This is how it should look if you typed it.
~~~ cpp
{% raw %}~~~ cpp{% endraw %}
int main() {
std::cout << "Hello world!" << std::endl;
return 0;
}
{% raw %}~~~{% endraw %}
~~~
The above code should be displayed like the following in the browser after it has passed through Jekyll.
I have recreated the actual output since I can’t get it to work and the next paragraph is wrongly rendered because the code above doesn’t work as it should.
You will notice that the closing ~~~ is missing at the bottom. That was how it was rendered.
~~~ cpp
int main() {
std::cout << "Hello world!" << std::endl;
return 0;
}
This is the actual HTML code produced by the code above.
On the last line, after the div, pre, code tags have been closed, the closing ~~~ is rendered as a beginning fenced code block.
And you will see why the next paragraph after the fenced code block is ruined.
I am not sure if this is a bug or if anyone has filed a bug report on it as of this writing.
But that just shows that as of this writing we cannot use {% raw %} and {% endraw %} to display raw fenced code blocks syntax.
<div class="highlight"><pre><code class="language-cpp" data-lang="cpp"><span class="o">~~~</span> <span class="n">cpp</span>
<span class="kt">int</span> <span class="n">main</span><span class="p">()</span> <span class="p">{</span>
<span class="n">std</span><span class="o">::</span><span class="n">cout</span> <span class="o"><<</span> <span class="s">"Hello world!"</span> <span class="o"><<</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span>
<span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
<span class="p">}</span>
</code></pre></div><div class="highlight"><pre><code class="language-text" data-lang="text">
Alternative to Showing Fenced Code Block Syntax
An alternative is to wrap the fenced code block within the {% highlight %} and {% endhighlight %} tag markup.
For this purpose only will I use such to minimize the use of non-standard Markdown syntax.
{% highlight cpp %}
~~~ cpp
int main() {
std::cout << "Hello world!" << std::endl;
return 0;
}
~~~
{% endhighlight %}You will see the following fenced code block syntax output in the browser:
1
2
3
4
5
6
~~~ cpp
int main() {
std::cout << "Hello world!" << std::endl;
return 0;
}
~~~