Skip to content

Make templates compatible with minijinja (Rust) #8112

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Mar 30, 2025

Conversation

squidfunk
Copy link
Owner

@squidfunk squidfunk commented Mar 25, 2025

This PR improves compatibility with minijinja, a template engine we're currently exploring. Additionally, it replaces several instances of Python function invocations with idiomatic use of template filters. All instances where variables have been mutated inside templates have been replaced. Most changes have been made in partials, and only a few in blocks, and all of them are fully backwards compatible, so no changes to your overrides are necessary.

Note that this PR does not replace the jinja template engine with minijinja. However, our templates are now 99% compatible with minijinja, which means we can explore alternative jinja-compatible implementations. Additionally, immutability and removal of almost all Python function invocations means much more idiomatic templating ☺️


🙋‍♀️ Want to help testing? Just check out this branch, and build your documentation with it – it only takes a minute:

pip install git+https://github.com/squidfunk/mkdocs-material.git@refactor/jinja-compat
mkdocs build

There should be no difference in output whatsoever. If there is, please let us know!

@squidfunk
Copy link
Owner Author

We've tested the changes on several big projects, and consider them safe to be merged. All changes are backward compatible, which means that no overrides need to be adapted. Only Jinja syntax has changed, but template semantics have stayed the same. The only thing that is different in behavior is that the JSON passed to the application will now include keys that are null, as minijinja does not allow to progressively construct dicts, as all values are immutable. Yet, this does not change behavior, it only adds a few more bytes while giving us the upside of almost 99% compatibility.

@squidfunk squidfunk merged commit c18630f into master Mar 30, 2025
4 checks passed
@squidfunk squidfunk deleted the refactor/jinja-compat branch March 30, 2025 09:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant