Multiple versions built from branches in GH pages?

[ixodie]

Hello,

I am using mike with mkdocs-material. I have gh-deploy setup with two jobs:

job1
----

on:
  push:
    branches:
      - main
    - run: pip install -r requirements.txt -q
    - run: mkdocs gh-deploy
    - run: mike deploy --push --update-aliases 1.0 latest
    - run: mike set-default --push latest

job2
----

on:
  push:
    branches:
      - release/v2.0
    - run: pip install -r requirements.txt -q
    - run: mkdocs gh-deploy
    - run: mike deploy --push 2.0

The goal is to have a 1.0 version which is latest (main) and a version 2.0 which is based on release/v2.0 branch.

It works fine when I commit to main (it becomes latest, 1.0 in the mkdocs version chooser).

When I commit to release/v2.0 it switches to 2.0 in the mkdocs chooser, as if it is completely overwriting the gh-pages branch which is what is processed via github actions to make my site.

My goal is to be able to independently commit to 1.0 or 2.0 and the gh pages should be updated with the rendered docs. I will manage the content differences between 1.0 and 2.0 via git merges, and eventually make 1.0 locked for edits.

This seems like a common workflow, where the support team is constantly improving existing docs (1.0) but development wants to start updating for a new version (2.0). Yet I must be doing something wrong because of the overwriting issue above.

Any ideas what I might be doing wrong?

[ixodie]

Another option I tried was do run mike deploy, and then checkout the other branch and do another deploy to a new version, but I couldn't get it to work properly.

[jimporter]

Why are you using mkdocs gh-deploy? It removes the entire contents of the gh-pages branch when calling it, so you'll lose any existing versioned documentation as well.

[ixodie]

Well that explains the problem. Thanks!

Would it be better to simply do:

mike deploy 1.0 latest
git checkout release/2.0 && mike deploy 2.0

instead of running two differrent jobs?

[jimporter]

So long as the jobs don't run in parallel, I don't see any issues with having multiple jobs for this.