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

Add support for multi-language documentations #73

Closed hmsdoc closed 2 years ago

hmsdoc commented 2 years ago

Hi @jimporter, mike works great with single-language documentations. But as far as I can understand, it is currently not possible to use it with multi-language documents that are created as described in this MkDocs Material discussion.

If so, is there a workaround you can recommend, that enables a combination of the multi-language and versioning features? Or are you planning to include this in a future version?

Thanks in advance!

jimporter commented 2 years ago

You can use --prefix=LANG to put your docs within LANG/ as a subdirectory. Then you'd have example.com/LANG/VERSION/.... Each language would be 100% independent of each other, so you'd have to be sure to keep them in sync, but that shouldn't be much extra work if you've got tooling set up for it.

Based on that link, it looks like this would work pretty much the same, with the caveat that you'd be generating one commit per language; I don't really see that as an issue, but if you don't like that, it should be straightforward to squash the commits before pushing upstream.

hmsdoc commented 2 years ago

Thank you very much for your suggestion! It worked exactly as you described. I was able to achieve the expected result via a GitLab Pages pipeline by adding the --prefix parameter and changing into the correct subdirectory to call mike for the corresponding language. I'm fine with having multiple commits (one per language).

jimporter commented 2 years ago

I'm pretty sure (with a relatively recent version of MkDocs), you don't even need to cd into the subdirectory. This should work too:

mike deploy --prefix=LANG --config-file=PATH/TO/LANG/mkdocs.yml
hmsdoc commented 2 years ago

Thanks for the hint! I wasn't aware that this config parameter even existed. Works perfectly!