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.