Versioning question and a bit more

[niden]

Greetings

I have been experimenting with mkdocs and mkdocs-material for a while now, in an effort to port a project's documentation from Jekyll. The project has versions and languages.

I looked into the language part and it was a bit daunting to tackle, and after talking to a colleague of mine, we decided to only support English, so that issue was solved.

I got all the documents converted to the way they should be and they show just fine. Running mkdocs-material locally helped with the migration process. In the end I deployed the docs in Cloudflare Pages and everything works as expected.

Here comes the versioning part and question.

I would like to have versions and checked the mike project. I did not however find a decent way to a) update documents if we need to (typos and the like) and b) publish a new version. Using mike to publish the new release seems easy but I am struggling to understand how that will be done in Cloudlfare Pages. At the moment all I do is push to the repo, Cloudflare Pages picks the commit, builds the site and then deploys it. So the part with mike publishing somewhere there is unclear. I did read about a way to do this using GitHub actions but then I would have to do this on a "release" workflow, when a new tag is created.

I was thinking of creating folders under my docs folder, one per version, to work with the version selector. For releases I would have to copy/paste all the contents to the new version folder and make changes there - appropriate to the new version. Then a git push would deploy the site to Cloudflare Pages.

Thoughts on the above?

[kamilkrzyskow]

Hello,
I never used mike myself, but after reading https://github.com/jimporter/mike#how-it-works I believe you can re-deploy the same version with any typo fixes you want and the rest of the deployed versions will remain untouched.

Considering how git works, mike has to create a new commit on top of the previous one even when modifying an older version, so I don't see any problems with fetching the last commit of the gh-pages branch via Cloudflare Pages.

GitHub actions but then I would have to do this on a "release" workflow, when a new tag is created

Can you provide the source where you read that you need tags?

Also Arduino-Cli uses mike 1.x for versioning: https://github.com/arduino/arduino-cli/tree/gh-pages you could maybe see how it compares to your versioning branch 🤔

[niden]

Thank you for the quick reply.

I guess I am not grasping the workflow, how it would work.

Right now, you push a commit, then Cloudflare clones the repo, builds the site (under say site) and then deploys that folder as the website.

With mike if I push a commit how would it know which version to commit/deploy? One could say that it will deploy always to the latest.

One way I thought about doing this was to keep a repo that has all the code mkdocs-material and mike need, and "compile" each version to a folder. Then move that folder to a different repo and commit that. Then that would be the site deployment but again too many questions there on how it will automatically be deployed in Cloudflare.

I will check the Andruino-Cli. Thank you for the resource.

As for the "release" workflow, there is a way where in the Actions CI you can trigger a workflow when a new release happens in a repo. Then in that release workflow you can do whatever - say run mike with the new release name/version

[squidfunk]

As another option to mike, you can also use the brand new built-in projects plugin which we're currently developing. It's still experimental (see this discussion for what it can already do), but it allows you to build multiple documentation projects together, e.g. different languages or different versions. We're in the midst of designing the API surface and expand it to cater to more use cases, so you're invited to give it a spin to give us feedback and help us transforming it into the simplest solution with your feedback.

Note that this requires a sponsorship, since it is currently solely available via Insiders. The Insiders program allows us to develop awesome features together with our most active users before releasing them to the general public.

[niden]

We got everything sorted out.

#6546

@squidfunk we will definitely explore the projects plugin down the road as an alternative. For now everything works great.

Thank you all for the help and pointers.