What are possible reasons for an include to not work in a template file?

[Andre601]

Full context: mkdocs/mkdocs#3888

My current issue is, that I'm unable to include a separate template file through the include option of Jinja2.

I've set the macros plugin's include_dir to docs/.overrides/ (Can't have it outside the docs folder due to the repository's structure) and have files api_docs/layout.md and api_docs/parts/constructor_summaries.md (relative to the mentioned include directory) set.

Now, using {% include 'api_docs/layout.md' %} works fine when injected into the markdown through a on_pre_page_macros python file, but {% include 'api_docs/parts/constructor_summaries.md %} in the layout.md file itself returns a TemplateNotFound error.

Manually adding the include in the page is adding the content as it should, so the issue is with the template not resolving the include for some reason.

What could be possible issues?

[fralau]

First of all, I want to make sure that everyone is on the same page, about the distinction between the MkDocs's standard Jinja2 templating engine, and the MkDocs-Macros templating engine? The first operates on HTML files, while the second operates (much earlier on the production chain), on the Markdown source, before rendering into HTML. They are completely distinct.

By default MkDocs-Macros considers the doc_dir as the root, because it is what makes more sense (see documentation page); but it can be changed, as you did, with include_dir.

I have never tried to use MkDocs-Macros to do templating, though I guess that could kind of work (because HTML code is ignored by the Markdown parser).

There is an avenue I would suggest, and that is to "trickle" values from the earlier to the later Jinja2 engine. In that way, you could import your dynamic values in the MkDocs Jinja2 template, while using the facilities of MkDocs-Macros. Is that more less what @kamilkrzyskow had in mind?

[kamilkrzyskow]

The docs/.overrides directory is missing, so I got the custom_dir from https://codeberg.org/Andre601/AdvancedServerList
I added placeholder macros templates files, which are added in the hook.
I also added a textwrap.dedent to the footer text.
Everything works as expected otherwise.

macros-andre.zip

[Andre601]

The docs/.overrides directory is missing,

That is weird... I simply selected the docs folder alongside the mkdocs.yml file and requirements.txt and did right-click -> "send to... -> Zip-compressed folder" on Windows.
So I guess it skipped that folder - alongside others, as you can see in the screenshot - when making the zip...

[Andre601]

Also, forgot to mention, but this version uses a different aproach where I inject the include statements of all template files in the page itself instead of using a main template file to include everything else from...

[kamilkrzyskow]

So was this resolved @Andre601? I have this weird feeling it didn't while it should given all the examples till now 🤔

That is weird... I simply selected the docs folder alongside the mkdocs.yml file and requirements.txt and did right-click -> "send to... -> Zip-compressed folder" on Windows.

I tried it myself, and only the first directory with the . prefix is included, if you remove .hooks then .overrides will be included. Neat edge case in Windows compressor 😆

Therefore, it's better to rely on 3rd party toold like 7-zip that won't have the same issues, but I also often recommended the Send to method.

[Andre601]

Yeah, pretty sure the issue is still there.

Like I said am I using a workaround by having the individual {% include '...' %} be added on the page through the on_pre_page_macros event. It's not too easy to have but A) it works and B) the page context is available for the template files.

[Andre601]

Wanted to share what I managed to achieve with the plugin:
https://preview.andre601.ch/@AdvancedServerList~398/api/reference/

All the pages under this link (with exception to the ones listing sub-pages) are having content generated from Page meta using templates.

Templates are included using this code snippet added as a module:

def on_pre_page_macros(env):
    footer = """
    
    {% if page.meta and page.meta.api %}
    {% include 'api_docs/constructor_summaries.md' %}
    {% include 'api_docs/nested_class_summaries.md' %}
    {% include 'api_docs/enum_summaries.md' %}
    {% include 'api_docs/method_summaries.md' %}
    
    {% include 'api_docs/constructor_details.md' %}
    {% include 'api_docs/enum_details.md' %}
    {% include 'api_docs/method_details.md' %}
    {% endif %}
    """
    env.markdown += footer

Changes are not yet merged, as I'm open for feedback on improving this (One plan is to maybe have a JSON file in the future to create the necessary stuff instead of page meta, but that's not yet clear).
You can find the PR and changes here: https://codeberg.org/Andre601/AdvancedServerList/pulls/398