Using --config-file to call two different yaml files that include different index files?

[DennisJDufrene]

Hi.

I have one repo where I want to build two sets of documentation that share all subdirectories in the docs folder. However, stylesheets, overrides, and /docs/index.md (landing page) are different.

Using mkdocs serve --config-file mkdocs-a.yml I can set my custom_dir to call overrides-a and my stylesheets extra-a.css versus mkdocs serve --config-file mkdocs-b.yml to set custom_dir: overrides-b and stylesheets extra-b.css.

Where I run into the issue is setting the nav for Home: to index-a.md versus index-b.md. Is there a way to call a different/custom index.md for the home page instead of just index.md and have them both live in /docs?

Thanks in advance!

[mocdaniel]

A quick search in the mkdocs documentation didn't reveal an option to do this, especially not in the context of mkdocs serve - it canonically renders the file index.md at the root level of your docs_dir at / of your docs, or falls back to a 404.

The docs regarding file layout in mkdocs can be found here.

What you could do during build-time is symlinking/copying the respective index-{variant}.md to index.md by providing the needed variant via e.g. ENV variable, then continuing to build the static docs referencing the mkdocs-{variant}.yml.

[kamilkrzyskow]

I agree that there is a need for a custom solution with file replacement / injection.

However, I would try to somehow use the --config-file value either via some Python launch script or hook instead of relying on an additional environmental variable.

Order of operation would be:

1. Prepare a bare index.md file that will be part of version control
2. Prepare variants inside of overrides directory outside of docs
3. Run the launch script which:
   • Loads the contents of the bare index file
   • Loads the contents of the selected alternative variant
   • Replaces the bare index file
   • Runs the mkdocs build process
   • Restores the bare index file (this is for local test development, as CI doesn't really need to restore the docs)
     • Also keep in mind that MkDocs could crash so add a try/except block or handle the restoration every time

A hook would also allow to pass variables to the Jinja2 environment and use those in conditionals inside the templates, so instead of 2 files there could be 1 file with different content branches.

BTW I don't know what's the difference but the mkdocs readthedocs isn't the official docs, and the last deployment was over 2 years ago, and the last official docs deployment was ~1 year ago https://www.mkdocs.org/.
https://app.readthedocs.org/projects/mkdocs/builds/
https://github.com/mkdocs/mkdocs/deployments