Is there a way to use macros to change navigation conditionally?

[hozn]

First of all, this is a great plugin; thank you for making this available to the community. I'm working on a project where we'd like to use this plugin with a lightweight soft of "feature flags" system to show or hide certain parts of our user documentation based on the presence of these flags. For the content, defining our own is_enabled macro works great. However, we're not sure on the best way to conditionally modify the navigation.

Currently we have this in the mkdocs.yml -- and we'd like to check the flags to determine if certain pages should be excluded

nav:
  - "Introduction": "introduction.md"
  - "Feature One": "feature-one.md"
{% if is_enabled("feature-two") %} 
  - "Feature Two": "feature-two.md"
{% endif %}

This does not work as-is, unsurprisingly. Is there another strategy to achieve this? Is the best option to subclass the plugin and override on_nav ? Or perhaps the easiest option is to just make a new plugin locally that does this one thing?

I also noticed that on_nav implementation in this plugin does store off the original navigation object as "navigation" var. Is there a hook that this plugin supports where that nav structure could be modified?

[fralau]

Thanks a lot for your appreciation! I had not thought about your use case, but it makes a lot of sense.

Indeed, Mkdocs-Macros plugin won't work directly with the snippet above, since the plugin renders only the markdown files.

You could take a number of approaches, depending on your use case and circumstances. 🤔 You wish to make this choice at build/serve time, right?

In that case, why don't follow your idea through, but without the plugin? A simple solution could be: you create source config file called, e.g. mkdocs_source.yaml which contains exactly the code you suggested.

You could write a Python utility that does more or less this:

1. Read the flags from a separate config file (e.g. doc_flags.yaml or doc_flag.toml according to your preferences) into a dictionary flags, using the appropriate Python module (typically pyyaml or tomllib).
2. Then put together a little jinja2 engine, which will process your mkdocs_source.yaml (with its jinja2 directives) into mkdocs.yaml (pure YAML). You pass your dictionary flags to the template engine. It's a few lines of code.
3. Optional: you could insert a jinja2 directive in your mkdocs_source.yaml to slam additional information into the extra section so that later, your Mkdocs-Macros directives could introspect (e.g. to write in a page: "This documentation has enabled {{ feature_one }}").

Then you would create a script that does this:

1. Pre-compile your config_source.yaml into config.yaml
2. mkdocs build or mkdocs serve

I hope this helps.

[hozn]

Thank you so much for the quick response! Your idea of preprocessing should work fine, yes. I will follow that approach -- maybe/hopefully can combine this logic into the same main.py file so I can share the implementation of the feature flag lookup logic between the macro and the preprocessor function.

[rachel-rigdon-sp]

@hozn Hi! Were you able to create a solution for this? I'm trying to do the same thing.

[fralau]

Hi, thanks for reaching back again, about this issue of conditional navigation. Jinja2 is very expressive.

However, Mkdocs-Macros is designed to work only on the markdown files -- that's its sphere of action (plus a few goodies around it).

Concerning the config file, it's a problem of the chicken and the egg. Mkdocs-Macros relies on the config file to read its variables (from extra). It wouldn't be able to read that YAML file if it had some Jinja2 in it (as in your example), since that would cause a syntax error. What should we do? Ask him to first strip the Jinja2 code out the config file? And then ask it to go back and reinterpret the Jinja2 code in the same config file which it had used as source... wouldn't we risk to get into a loop?

The underlying question is: where would you store your feature_two variable? As a Jinja2 variable?

[fralau]

The proper way to do that would be to use a hook on the on_nav event.

If you don't want to write your own plugin, you could just use a hooks.py file:

# hooks.py
def on_nav(nav, config, files):
    # Your logic here
    return nav

And, in the config file:

hooks:
      - hooks.py

Your on_nav would be able to read the extra part of YAML file (which is quite easy to implement).

[fralau]

To complete the answer above, I would make a separate file (e.g. navigation.yaml) that contains the navigation + the jinja2.

#navigation.yaml
- "Introduction": "introduction.md"
- "Feature One": "feature-one.md"
{% if feature_two == True %} 
- "Feature Two": "feature-two.md"
{% endif %}

In that way, you could:

1. Read the extra section of the config into an extra dictionary using the yaml package (I guess you would have your feature_two variable in it).
2. Define a jinja2 template, passing the extra dictionary as the environment of the template, and apply to navigation.yaml to produce the yaml code.
3. Read that yaml a list that you can use in the on_nav function.