Mkdocs: Allowing Jinja tags/variables/expressions inside the Markdown files?

[twardoch]

The Jekyll system used by Github Pages is clever because it not only allows Liquid templating tags/variables/expressions inside the “template definitions” but also inside “template content”.

For example, the README.md of my Github user page repo has this simple content:

# Adam Twardoch

Public repositories:

{% for repo in site.github.public_repositories %}
[{{ repo.full_name }}]({{ repo.html_url }})
: {{ repo.description }}
{% endfor %}

Jekyll gets rendered into:

<article class="container content">
    <div class="page">
        <h1 id="adam-twardoch">Adam Twardoch</h1>
        <p>Public repositories:</p>
        <dl>
            <dt><a href="https://github.com/twardoch/1337-Scheme">twardoch/1337-Scheme</a></dt>
            <dd>1337 - A Color Scheme for dark Sublime Text</dd>
            <dt><a href="https://github.com/twardoch/clinker-mktheme">twardoch/clinker-mktheme</a></dt>
            <dd>A clean, responsive MkDocs theme</dd>
            <dt><a href="https://github.com/twardoch/compositor">twardoch/compositor</a></dt>
            <dd>A basic OpenType GSUB and GPOS layout engine.</dd>
            ...
            <dt><a href="https://github.com/twardoch/ufo2ft">twardoch/ufo2ft</a></dt>
            <dd>A bridge from UFOs to FontTool objects (and therefore, OTFs and TTFs).</dd>
            <dt><a href="https://github.com/twardoch/urw-core35-fonts">twardoch/urw-core35-fonts</a></dt>
            <dd></dd>
            <dt><a href="https://github.com/twardoch/varfonts-ofl">twardoch/varfonts-ofl</a></dt>
            <dd>Variable OpenType fonts under the SIL OFL license, samples and development tools &amp; workflows</dd>
        </dl>
    </div>
</article>

My Liquid template has the portion {{ content }}. That’s where the processed content of my README.md goes, but that content is also processed through the Liquid templating system before it’s converted from Markdown to HTML.

An MkDocs Jinja-based template has the analogous {{ page.content }} portion where the HTML output from the Markdown conversion goes.

But my understanding is that currently, I cannot insert Jinja2 structures (tags/variables/expressions) into my Markdown files. That would make a lot of sense though, don’t you think?

Or could that be realized through a custom Python extension (of the preprocessor kind)?

Best,
Adam

[twardoch]

Ps. There’s a repo that showcases this. It includes an index.markdown file that contains Liquid inclusions. It seems that In order to prevent the Liquid templating engine from processing the Liquid constructs, one must surround them with {% raw %}...{% endraw %}.

In other words, this gets processed through Liquid:

{% for repo in site.github.public_repositories %}
[{{ repo.full_name }}]({{ repo.html_url }})
: {{ repo.description }}
{% endfor %}

while this gets passed through:

{% raw %}
{% for repo in site.github.public_repositories %}
[{{ repo.full_name }}]({{ repo.html_url }})
: {{ repo.description }}
{% endfor %}
{% endraw %}

This is pretty neat, and I think having something like this in MkDocs would make a lot of people happy!

[waylan]

Personally I detest Jekyll's Liquid template support inside Markdown. Including code blocks which contain template syntax requires extra escaping (as you demonstrate--yes that is a negative not a positive) and there is that secondary (non-Markdown) syntax for code blocks among other things I find disgusting. Either you write Markdown or something else. Not some hybrid between the two.

That said, I do see the value of being able to insert variables into your Markdown text, which is the subject of #304. Whether adding that support includes more (logic) or less (logic-less) is a discussion and decision which is being made there. Therefore, I'm closing this as a duplicate.

[rkoe]

By the way: I've created a simple way to include Jinja2-Macros in the Markdown-Template:
https://github.com/mkdocs/mkdocs/issues/304#issuecomment-460058741