Toc

[susuhahnml]

No description provided.

[VictosVertex]

The last commit of this basically reverts the rendering changes from #7, turning it back into a two-pass rendering for everything.

While this does simplify the templates, as we do not require convert_markdown anymore and could even remove the entire part of setting a variable first, I don't know if this could have other unwanted side-effects.

According to https://mkdocstrings.github.io/reference/handlers/base/#mkdocstrings.handlers.base.BaseHandler.do_convert_markdown the function is supposed to be used within templates.

The mkdocstrings handlers for python and vba do a basic render of the template, as seen here:
https://github.com/mkdocstrings/python/blob/main/src/mkdocstrings_handlers/python/handler.py#L406
https://github.com/mkdocstrings/vba/blob/master/mkdocstrings_handlers/vba/_handler.py#L161

Then they do the markdown conversion within the templates. However, their extend of markdown usage seems to be docstrings. At least I'm so far unable to find anything that isn't passed directly as a variable.

So apparently, we're doing more (or do it different) in markdown than any of the projects I've looked at so far, which may be the reason why they are able to use the function as intended, while we do a full two-pass rendering.

My thoughts on this:

• simply do a two-pass render as you propose and see whether there are any side effects or not
• fix the errors caused by the current in-template rendering in a different, if possible
• simply do most of the templating in html and pass things like dependency graph markdown as variables (if that helps), so the DependencyGraph would provide the markdown directly

I'm fine with any of these approaches, just wanted to outline how things are done elsewhere.