Advice on using mike with my build process

[SteveRosam]

We build our docs with GitHub actions. We do a bunch of stuff like pull in another repo with the multi repo plugin Build the docs with squidfunks material plugin.

The full build yaml can be found here if you want to have a look: https://github.com/quixio/quix-docs/blob/main/.github/workflows/build-commit-subfolder.yaml

The result from the docs build is then deploy to GitHub pages:

  # Deployment job
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v1

So the question: Anyone got an opinion on how I can build versions of docs with my build script?

My initial thoughts are to add something like

mike deploy 1
mike deploy 2
etc

to the build.

Or perhaps I should be changing the build step to build with mike and push to github. But im not sure that will be compatible with our development process. e.g. develop locally, push to a dev environment then promote to prod.

Does anyone else do it this way?

[jimporter]

But im not sure that will be compatible with our development process. e.g. develop locally, push to a dev environment then promote to prod.

At a guess, I'd try this:

• For PRs/dev branches, run something like: mike deploy $VERSION && git archive -o site.tar.gz gh-pages && upload-to-dev site.tar.gz. That does generate a new commit on the gh-pages branch of your CI job's repo clone, but you don't have to push it upstream, so no worries there. Or you could just use mkdocs build as you currently do; I'm not sure there's much point in pushing old documentation to a dev env, since those old docs wouldn't have any changes.
• When merging to your default branch, run something like mike deploy $VERSION --push to generate the docs again and push the changes upstream.

[SteveRosam]

Thanks, I was wondering if there was a way to see the output from the build? With mkdocs build you get the site directory with the built docs. Is there a folder somewhere with the built mike docs?

[jimporter]

Yeah, it's the latest commit in your gh-pages branch. You can see it locally via mike serve (which pulls from your gh-pages branch, even if it's not the current branch), or via the git archive example above.

[SteveRosam]

Where does it get the gh-pages details from? I assume it is doing that because I get what I expect when doing mike serve. Just wondering how it works.

[SteveRosam]

fyi on windows when i do

mike deploy 0.5.2 then git archive -o foo.zip i get a 0 byte zip file

im a bit of a noob at this so not sure how significant a deviation this is from what you posted above

[jimporter]

The easiest way to see what's happening is to look at the diffs in your gh-pages branch, but essentially mike is treating that branch as an archive for build artifacts (in this case, docs). Each time you call mike deploy $VERSION, it builds the site and then generates a commit on gh-pages that puts the generated docs in the $VERSION/ folder. This way, all the other versions in the gh-pages branch are undisturbed, so that when Github serves your docs, all the versions are there.

Ultimately, this is all just a hack building on top of Github's hacky behavior of using gh-pages to host generated documentation. I think the cleaner solution would be a real webserver that you can push generated docs to, and it figures everything out. But Github Pages is free, and very convenient for smaller projects. :)

---

git archive -o foo.zip

You need to specify the branch you want to make an archive of:

git archive -o foo.zip gh-pages

[srosam]

Thanks for the detailed explanation! I think I get it and (while driving the kids to school) I think I figured out how to proceed.

[SteveRosam]

Hi. I cloned my repo to another repo so I could play with this in safety.

I have run mike deploy 1.0 --push and mike deploy 2.0 --push and can see folders in my gh-pages branch. Running locally with mike serve yields a drop down with the versions in it.

But I don't see the versions on the published pages. I'm suspect that it's because my gh-pages is deployed by a GH action and not from the repo being updated. I tested this by changing the pages setting to look at the gh-pages branch instead and pushed another version of the docs. This resulted in my versioned docs appearing as expected.

So I think all that's needed is a simple alteration to the build script to run mike deploy ... and to change the config to look for changes to the correct branch.

[SteveRosam]

I tried adding this step to my build script:

      - name: Deploy docs
        run: mike deploy 2.5 --push

I get this error error: error getting config 'user.name'

I have tried adding user.name and GIT_COMMITTER details like this:

      - name: Deploy docs
        run: mike deploy 2.5 --push
        env:
          user.name: build-bot
          GIT_COMMITTER_NAME: ci-bot
          GIT_COMMITTER_EMAIL: ci-bot@example.com

but get the same error.

I thought I would have to pass it a github token or something giving write access to the repo.

The build script already has this at the top:

permissions:
  contents: write
  pages: write
  id-token: write

[jimporter]

GIT_COMMITTER_NAME / GIT_COMMITTER_EMAIL are only supported in the development version of mike. If you're on the release version, see here: https://github.com/actions/checkout#push-a-commit-using-the-built-in-token

[karl-johan-grahn]

You have some working workflows here: https://github.com/stakater/.github/tree/main/.github/workflows

Example repo using them: https://github.com/stakater/test-doc-versioning