search

jimporter / mike

Manage multiple versions of your MkDocs-powered documentation via Git
BSD 3-Clause "New" or "Revised" License
534 stars 47 forks source link

❓ How to use `mike` locally ? #77

Closed ghost closed 2 years ago

ghost commented 2 years ago

I would like to use mike, but I don't want to host my docs on github pages.

If possible, I would like to avoid mike committing anything to my branches.

So is it possible to use mike so that the docs versions are stored locally (as in : in the current branch), and let me commit the changes by myself ?

I'm not sure I'm very clear, feel free to ask for clarifications ! Thanks for your patience.

squidfunk commented 2 years ago

Related:

jimporter commented 2 years ago

The short answer is that that's not possible in mike. Its sole purpose is to use a git branch as an archive to host your compiled docs, so removing that would mean mike is just a few lines of Javascript to put a version selector on a webpage. (For the Material theme, it wouldn't even be that; the version selector code lives in the Material theme repo.)

I see you want to use RTD to host your docs. In that case, I recommend just using that without getting mike involved at all. Since mike's goal is to be an alternative to RTD for people who want to host on Github (or a similar git forge), it doesn't really make sense to combine the two. If there are issues with how the Material theme interacts with RTD's version-selection logic, that's likely a bug in the Material theme, since mike isn't (or shouldn't be) involved.

More generally, if we're being precise, the thing that the Material theme added support for isn't "mike" itself, but rather the "mike versioning metadata scheme" (i.e. versions.json). Any tool that can generate a compatible versions.json file and put it in the right place should work with the Material theme's version selector. If you want a tool that manages versions in a different way, you can just build it however you like. So long as it makes the appropriate versions.json file, it should work with Material. (That said, if your goal is to host on RTD, I don't think they use a versions.json file, so you'd probably need to something completely different from this. That's not really my area though.)

squidfunk commented 2 years ago

@jimporter thanks for the explanation! I'll point future users asking similar questions to this great answer.

jdomag commented 2 years ago

@squidfunk @jimporter How to use versioning then in Material without mike and host it with e.g. nginx? Is the structure of versions.json described somewhere?

squidfunk commented 2 years ago

@jdomag https://github.com/jimporter/mike/issues/80#issuecomment-962273298

jimporter commented 2 years ago

Is the structure of versions.json described somewhere?

It's at the end of the README: https://github.com/jimporter/mike#for-theme-authors