Versioning of sub-folders

[srinisubramanian]

My main documentation site has multiple sub folders, each describing a separate product/app.

For e.g the main folder is mkdocs/docs and there are multiple products defined at mkdocs/docs/product1, mkdocs/docs/product2 etc. THe need is to setup versioning for one of the products ie. product2 and not the entire set.

Is this possible? If not directly possible is there any other way to achieve it?

[jimporter]

Use deploy_prefix and configure a few independent collections of docs (with their own mkdocs.yml files) and deploy them individually as needed.

[srinisubramanian]

Apologies .. but I am just getting started so not sure i am getting this right.

Is the solution to have a single mkdocs project but in the subfolder have an additional mkdocs.yml and use deploy-prefix in the sub-folder and version it? Or is the recommendation to have two projects and then merge deploy the final output?

[jimporter]

The latter. You'll want to use multiple independent MkDocs projects (probably in subdirectories of your repository). Then you can deploy them individually, and with deploy_prefix they'll each go into the specified subdirectory of your gh-pages branch.

[aleksandrserbin]

@jimporter what should be the approach when docs are not independently-versioned? Let's say I just want /page to be redirected to /0.1/page/ the same way as / is redirected to /0.1/?

[jimporter]

Sorry, that's not supported. You could manually create such redirects yourself, but mike has no facilities to do this automatically.

[aleksandrserbin]

I see, thank you for the reply. Would it be a good candidate for improvement though? If so, I can try to prepare some implementation draft. If it is something considered unimportant though, it is understandable as well.

[jimporter]

I'd prefer to keep a feature like that separate from mike. By default, mike tries pretty hard to prevent any risk of conflicting filenames by ensuring that (almost) everything lives in a controlled set of sibling directories (i.e. each version you've deployed). While you could probably add enough error handling to make a feature like this safe, mike is already quite a bit more complex than I planned for it to be, and I need to be careful about increasing the maintenance burden of this project even further.

In the longer term though, I'd like to add plugin support (see #161) so that users with specific needs have a way to modify their deployments. That way, I can keep the number of moving parts in the mike core to a minimum.

[aleksandrserbin]

Nice, thank you 🙂

[pmdirector]

I too have need for a documentation site with multiple products, each with its own versioning. Followed the above answer, works locally using mike serve, but I had some issues when publishing using GitHub Pages, which means I went astray somewhere. This is what I did.

1. Start a new repo with folders home, product_A, and product_B.
2. Create multiple mkdocs projects, one in each folder.
3. For simplicity, start all versions at 1.0, so build all projects with mike deploy 1.0 latest
4. Build product_A docs with deploy_prefix set to product_A, similarly for product_B. No deploy_prefix for home docs.
5. Push main and gh-pages branches to remote, and publish from gh-pages branch.

Result: No website found at root of domain. Redeploy home project with deploy_prefix set to home. Website found at domain/home.