Having a versioning working locally

[ghost]

As far as I understands, mike require a git repository with a gh_page branch. That's why versioning does not work with mkdocs serve, and you have to use mike serve.

I'm using RTD, and it seems I can't use versioning in Material-for-MkDocs with mike.

Is there any alternative to mike that would work properly with RTD ?

---

Alternatively, how can I modify the theme to :

• Build each version in their own folder, and have the version selector points to the right folder
• Maintains several sub folder on MD files, and have the version selector points to the right one (I don't mind breaking changes in MkDocs breaking older versions of my docs)

[squidfunk]

First, I'd recommend asking on the mike issue tracker whether there are possibilities to work around the current limitations. As I understand, mike is pretty flexible. Second, you could come up with a custom process, building multiple versions into multiple folders, as long as you create the versions.json that is generated by mike, and enable mike as stated in the configuration. Although you'd not be using mike, Material for MkDocs will just pretend you are.

[squidfunk]

Great, glad I could help.

As an additional note explaining why we choose mike over other existing solutions: the basic idea is that the versioning of the docs follows the versioning of your software or product. This has the nice property that the git tree is used as a source of truth, albeit it makes serving multi-doc versions locally less optimal. If you'd version docs in folders, your git repository will grow quadratically with each version, because for a new version, you'll have all files of the previous version, plus the added changes, which are all added to the tree. While this might be a sound approach when there are only a few versions, it might slow things down significantly when there are many. And so, each approach has its up-and downside.

[astariul]

Edit : this is my personal account :)

Your additional note is much appreciated. I understand the downsides of local versioning. Thank you !

---

your git repository will grow quadratically with each version, because for a new version, you'll have all files of the previous version, plus the added changes, which are all added to the tree.

My limited understanding of Git does not follow ^^
I thought that if a file did not change, Git does not store the file again. Since the docs of our previous versions are not supposed to change, it will just store the files once, right ?

[squidfunk]

It's correct that for text files, git will only record changes. However, if you have a Markdown file, and this file is included in each version of your docs in a separate folder, then git will have as many copies as you have versions of that file. If you change a single line in each version, the whole file will be included nonetheless, since it's at different locations in the tree.

[squidfunk]

It's not quadratic though, that's my mistake. For a file with N lines, git will store 2xN lines when you copy the file to a new folder each time. On the contrary, if you have a file that doesn't change between versions, git will have no additional overhead (except for the metadata it manages anyway). So it grows linearly with each new version when using separate folders, and has constant growth in the number of changes when using mike's approach.

[astariul]

@squidfunk Thanks for checking !

[ghost]

For future reference : I could make the versionning work locally (without mike) by simply adding manually the versions.json as you mentioned @squidfunk. Thanks for the help.

Here is a google colab reproducing it : https://colab.research.google.com/drive/1wShWQsGRfBtQbpsqzplDsiuTwba5mEa9?usp=sharing

---

Now I just have to see if I can glue these things together with RTD !

[zertrin]

The link to the google colab says the document can't be found. Could you include your steps directly here? The for future reference part of your comment is unfortunately not true any more 😢