Multi-branch deployment

[opensource-coder909]

Hi there

How can I deploy my mkdocs-material site on different branches at the same time so a person can view my mkdocs documentation in different branch versions?

Greedings

[kamilkrzyskow]

Hello @opensource-coder909,
I don't quite understand the wording of deploying to different branches. If you mean a git branch then it's typically the source of the site not the destination. Also GitHub supports only one GitHub Pages instance for a given repository so you'd have to provide more details.

MkDocs generates static HTML files, so as long as you properly set the root of the page via the site_url option, then you could include multiple sites on one GitHub Pages instance which would differ in the root directory.

You can look at versioning, which applies the same principle of having multiple versions of the page available:

• https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/#setting-up-versioning
• https://mkdocs-material.github.io/example-versioning/latest/

Each branch you have could be a different version.

[opensource-coder909]

Thanks for the reply @kamilkrzyskow !

I would like to have a staging instance - where I can see the preview of the modified doc. After reviewing I would like to deploy it into production.

I thought it is easy make it via branches. Is that not possible in this case?

Edit: Versioning is nice but I don't want that all people in the world can see the staging area.

[kamilkrzyskow]

Is that not possible in this case?

Depends on the backend, deployment solution you're using, and your plans, in general that's possible.
Gothic Modding Community uses a main branch for GitHub Pages and dev branch which is published on a custom domain on a VPS.

• https://github.com/Gothic-Modding-Community/gmc/

Please ignore the failing main branch badge 😅, there is a delay on the review of the dev branch so it wasn't merged back.

• main workflow modifies the gh-pages branch, which is later deployed via GitHub Actions
• dev workflow modifies the gh-dev-page branch, where a webhook detects the changes and the vps fetches the changes (that's my understanding of it, I'm not the maintainer of the VPS, so haven't seen the solution in full)
  The same could be used with a staging branch.

If you plan to host 2 variants of the page on GitHub Pages, then there is either the method with the multi directory in the root like mike does, or you'd have to use 2 repositories to support two instances of the GitHub Pages.

[opensource-coder909]

Thanks for the detailed information.

use 2 repositories to support two instances of the GitHub Pages.

I think i try this way