Markdown within HTML template override

[Archmonger]

I am trying to override the home.html template by following the built-in .overrides/home.html template.

However, there are a few things that are slightly easier to do in markdown, such as syntax highlighted code blocks.

I didn't find a Jinja tag for code blocks in the mkdocs-material source. So instead, I attempted using the mkdocs-include-markdown plugin within my home.html override:

{% block tabs %}
<div markdown>
    ```python
    print("Hello World")
    ```
</div>
{% endblock %}

But it doesn't appear to work. Can someone help me figure out how to hijack my way back into markdown from a template?

[squidfunk]

Judging from the plugin's README, it seems you need to put your Markdown in a file to include it from a template:

{% include-markdown "docs/includes/header.md" %}

That being said, we already have developed some promising ideas how to govern non-linear pages (like home page templates) from Markdown more easily. We'll explore that in the future and keep you all updated!

[Archmonger]

Apologies, I am clearly more sleepy than I thought I was.

I meant to say I was trying to use the md_in_html plugin for this.

[Archmonger]

Same question still remains though. I just tried out the mkdocs-include-markdown plugin and unfortunately the dash - in the template tag name is an invalid symbol in HTML override templates. It's invalid jinja in general so I'm surprised it even works via markdown.

{% include-markdown "test.md" %}

Does mkdocs material have any internal template tags I could use to render markdown?

[squidfunk]

md_in_html is a Markdown extension, not a plugin. It won't help you, because you're in template land, not in Markdown land. Regarding the mkdocs-include-markdown plugin you should ask the maintainer of the project. We're maintaining Material for MkDocs, not every extension that can be used with it 😉

[Archmonger]

I will assume that means mkdocs-material doesn't have any undocumented template tags for rendering markdown. This could be a good feature for your non-linear pages overhaul?

In the meantime, I will PR mkdocs-include-markdown to fix the invalid syntax to see if it could potentially help my oddball scenario. Worst case I'll have to semi-manually create codeblocks in my overrides/home.html.

[squidfunk]

No, there are currently no undocumented tags, and yes, it's exactly the direction we're exploring.

[Archmonger]

Out of curiosity, has there been any progress on non-linear page handling?

If not, should I create an issue for tracking?

[squidfunk]

Well, Markdown rendering is done by Python Markdown, which is invoked by MkDocs as part of the rendering process, whcih uses Jinja, not by us. I'm not sure what the best place to ask this question is, but definitely not here. Maybe ask the maintainers of MkDocs, as MkDocs ties everything together.