I need a bit of help

[Imzxhir]

Description: I would like to add a version and then commit something to that version. I've already setup one version which is 5.7.1 but how would I add another one and keep 5.7.1 as a version? This is what the build script looks like for the docs: https://github.com/Imzxhir/journeymap-docs/blob/main/.github/workflows/deploy.yml

[jimporter]

Don't use mkdocs gh-deploy; this is an alternative to that command, and they shouldn't be used in concert.

Also, don't use --force. It can wipe out the contents of your branch. You should only force-push a branch if you're 100% sure you know it's the right thing to do; this is why mike v2.0 removes the --force option entirely (users who really need it can use git push --force directly).

Since I'm guessing you added --force because it wasn't working without it, please see this section of the README. You need to make sure you've fetched at least the last commit of your gh-pages branch so that mike has the proper basis to work from.

[Imzxhir]

So, would mike deploy --push --update-aliases 5.8.5 latest -F ./config/en/mkdocs.yml after running git fetch origin gh-pages --depth=1 and removing the --force work?

[Imzxhir]

Don't use mkdocs gh-deploy; this is an alternative to that command, and they shouldn't be used in concert.

Also, don't use --force. It can wipe out the contents of your branch. You should only force-push a branch if you're 100% sure you know it's the right thing to do; this is why mike v2.0 removes the --force option entirely (users who really need it can use git push --force directly).

Since I'm guessing you added --force because it wasn't working without it, please see this section of the README. You need to make sure you've fetched at least the last commit of your gh-pages branch so that mike has the proper basis to work from.

I've now removed the --force command from deploy.yml as seen here https://github.com/Imzxhir/journeymap-docs/blob/main/.github/workflows/deploy.yml . I got the command from the docs of material for mkdocs: https://squidfunk.github.io/mkdocs-material/publishing-your-site/#with-github-actions

[jimporter]

So, would mike deploy --push --update-aliases 5.8.5 latest -F ./config/en/mkdocs.yml after running git fetch origin gh-pages --depth=1 and removing the --force work?

Something like that should work.

I've now removed the --force command from deploy.yml as seen here https://github.com/Imzxhir/journeymap-docs/blob/main/.github/workflows/deploy.yml

Yes, but you didn't remove the mkdocs gh-deploy step. That really does need to go, since it publishes unversioned documentation, which you almost certainly don't want.

I'd recommend filing an issue with the Material theme about improving their documentation.

[Imzxhir]

I didn't know that the mkdocs gh-deploy needs to be removed, I'll remove it now.

[Imzxhir]

When adding a new version, do I need to deploy that version and then make a change / commit?

[jimporter]

It really depends on the workflow you'd like for your project, so I'm not in a position to say what you need to do (except in very general terms).

If you want to add a new version (for example, you previously deployed 1.0 and now want to deploy 2.0), then you can just run mike deploy 2.0. The old 1.0 docs will still be there, but now you have a new set of docs for 2.0. Of course, you can also add aliases for this new version, so if you had previously run mike deploy 1.0 latest, you might want to mark your new 2.0 docs as latest now: mike deploy 2.0 latest --update-aliases.

To get a better feel for how this works, I'd recommend first reading through all the documentation on building your docs, and then trying it out locally. Just call mike deploy ... without pushing upstream, and then use mike serve to create a local webserver to check things out. Once you feel like you've found a process that you're happy with, only then add this to your Github CI.

EDIT: When you call mike deploy, it should always create a new commit (unless you're using the latest development version and the commit would have had no changes). To help understand what's happening, you can look at the diff for these commits. Since mike is all about producing Git commits, you can use all the various Git tools you like to examine the results.

[Imzxhir]

To check my undertanding for the command mkdocs gh-deploy. When it's already used once and generated the docs on another brand and your using mike as a version provider, you can safely remove it from the Github CI script since it doesn't need to generate the docs again and mike will takeover by publishing new versions and editing them.

[jimporter]

Correct.

[Imzxhir]

This can be closed as my issue has been resolved.