Menu not rendered when using macros inside H1

[BoxedBrain]

Hi,

I am using macros inside some H1 tags. e.g. # Configuration of {{feature-x.name}}

The page title works as expected, but inside the menu it's displayed raw. Is it somehow possible to solve that using macros and without specifying the menu entry manually?

Thanks!

[github-actions[bot]]

Welcome to this project and thank you!' first issue

[fralau]

It's interesting... I had not thought about that and nobody tried so far, obviously. Yes, one could want to have a page with a variable title. 🤔

But could tell me how come you had this use case? (what's the general logic of having pages with variable titles, so that I could see if there is not another way?)

That's my idea of how it could work, if we tried to fix this: exploit the on_nav() event; and run through all the page titles, and attempt to render them (convert from text + jinja2 to raw text.

[BoxedBrain]

@fralau we are currently discussing the renaming of some product features. Therefore, I thought about replacing them with a variable to do changes quickly and easier everywhere. Also, we use some of them in our headings, and that's how I came across this issue.

[fralau]

@BoxedBrain I can see how it makes sense... From a functional viewpoint, if we push the requirement of "translating macros" to its logical conclusion, then it might also apply to header text, which goes into the building of menus.

However, as I mentioned, it's a completely different thing "under the hood", which obeys to a different logic: we would need to develop something completely new, in a new direction.

Why not?... 🤔 But it's not something I would invest my time in, without thinking first.

[fralau]

What do we want to do with this issue?

[fralau]

Considering the list of events provided by mkdocs' documentation:

We should use the on_nav() event to, somehow, list and render all macros in the titles. That event (already used in the code), is executed after on_config(), hence the renderer (MacrosPlugin.render()) should be available for work.

[fralau]

@BoxedBrain Here is the result of my experiments: I made the change for the navigation on my dev environment and it does work.

However, it won't work if the macro is directly in the Header 1 of the page (problem of the chicken and the egg, which I haven't been able to solve yet).

What works, is to write the variable title (with the macro) in the nav section of the mkdocs.yaml file, e.g. :

nav:
    - Home: index.md
    - Environment for {{ unit_price}}: environment.md
    - Second:
        - Also for {{ unit_price}}: other.md
    - Not interpreted: literal.md

It means you cannot use meta variables in the page. But if your feature-x variable has been defined programmatically in a module (I suppose it is) then that could work for you?

Here is the changed code in on_nav:

from mkdocs.structure.nav import Section

        # Render also the navigation items, so that macros are interpreted
        # also in navigation
        # solution to issue #144
        def render_nav(nav):
            for nav_item in nav:
                try:
                    nav_item.title = self.render(nav_item.title)
                except AttributeError:
                    # not title in pre-page navigation, do nothing
                    pass
                if isinstance(nav_item, Section): 
                    # for second, third level titles
                    render_nav(nav_item.children)
        render_nav(nav)

[fralau]

Note: I did not use the code above. More simply, I made the program render the title of the page (interpret the macros), just after rendering the macros of the page itself. Since navigation is woven into the HTML page after all pages have been rendered from mkdocs to HTML, it works.

[BoxedBrain]

Hi @fralau, thanks for your effort! We moved away from using macros in h1. But it looks like it is relevant for @sverdoux / https://github.com/fralau/mkdocs_macros_plugin/issues/171

[fralau]

This update was pushed in mkdocs-macros 1.0.2 on pypi.