Upcoming deprecation (+ breakage in your case) regarding custom templates for mkdocstrings

[pawamoy]

Hello 🙂

I've been working on the Python handler of mkdocstrings, renaming templates from *.html to *.html.jinja as a quality of life improvement (syntax highlighting by default).

The change is backward compatible: previous users who were overriding templates can continue overriding *.html templates instead of *.html.jinja ones. They'll see an INFO log in MkDocs' output stating that this is deprecated and that the message will be a warning after some time, failing strict builds.

However, and I'm glad I thought about testing your project (because I remembered you had some custom templates), this would be a breaking change in your case, because you're overriding the base templates themselves, which was probably not intended.

To explain what will go wrong here, mkdocstrings allows overriding templates with custom ones, by extending the base templates (using blocks) or by completely replacing them (not using the extends Jinja tag or not using blocks).

docs/
  _templates/
    python/
      material/
        function.html

{% extends "_base/function.html" %}

{# your custom contents or blocks #}

You can see there are two template layers here, one under material, these are your custom templates, and one under material/_base, these are mkdocstrings base templates, which shouldn't be overridden (that's one of the reason it's called _base with an underscore).

With the upcoming change, mkdocstrings behavior will be:

• Look for a material/function.html template. If it exists, log a deprecation message (info) and use it. If not:
  • Look for a material/function.html.jinja template.
  • If there is a custom template with this name, it takes precedence.
    • If it extends _base/function.html, log a deprecation message (info).
    • If it extends _base/function.html.jinja, don't log anything.
  • Otherwise the default function.html.jinja template is used, which extends _base/function.html.jinja.

Since you don't override any function.html or function.html.jinja directly under material, the default function.html.jinja will be used, and it will extend _base/function.html.jinja, not _base/function.html, which you override. Therefore the template you override will become unused, and your customizations won't apply.

The solution here is simply to move your templates up by one level, into material, and removing the material/_base then empty folder 🙂

I can send a PR if you'd like.

[github-actions]

We found the following entries in the FAQ which you may find helpful:

• Why do some key combinations never make it to my app?
• Why doesn't Textual support ANSI themes?

Feel free to close this issue if you found an answer in the FAQ. Otherwise, please give us a little time to review.

This is an automated reply, generated by FAQtory

[pawamoy]

I added a check that will log a warning when base templates are overridden, so at least your docs won't silently "break".

[pawamoy]

Oh, just noticed you've pinned mkdocstrings-python anyway, so no need for a PR now. I'll close this issue but keep in it mind when you want to upgrade 😄

[github-actions]

Don't forget to star the repository!

Follow @textualizeio for Textual updates.

[willmcgugan]

Thanks for the heads up!

[pawamoy]

Of course! Here's the PR in mkdocstrings-python, for reference: mkdocstrings/python#155