Github deployment for dummies?

[nickriches]

Hi. I am trying to build a course handbook with mkdocs. I have no problem serving and building websites locally, but have spent hours trying to deploy via github. The instructions on mkdocs-material are brief. Has anyone put together a detailed step-by-step guide? Would netlify or gitlab offer a better solution?

Here are my basic steps

(a) Create a repository on github
(b) Clone to my computer (I use github desktop)
(c) Create mkdocs site (e.g. mkdocs new . and mkdocs serve).
(d) Push to origin
(e) Change name of main branch to gh-pages

Thanks.

[nickriches]

This site seems helpful: https://blog.elmah.io/hosting-a-mkdocs-driven-documentation-site-on-github-pages/

It suggests running gh-deploy main branch, and a gh-pages branch will automatically be created in github.

[nickriches]

I am getting a 404. Here are my steps:

(1) Create repository in github and clone to local computer
(2) Set up mkdocs site locally (with "build" command).
(3) Create ci.yml file in github (under .github/workflows) and save to main branch
(4) In Github Settings let Github know that I want to use "Github Actions" to create pages.
(5) Push local files to origin

When I go to Actions I can see that ci.yml has run. It tells my my website has been created. But when I go to the relevant address I just get a 404.

[squidfunk]

You might need to wait a bit until it shows up. Also make sure that your GitHub Pages branch is set to gh-pages:

[nickriches]

Thanks. That's wonderful. It now works. What confused me is that the site is being deployed by a github action, but in the pages section you don't select a github action, but you build from a branch. I had it set for "deploy from github action" assuming this referred to the ci.yml file (but I was also surprised that the url didn't pop up when I did this, which I guess is a warning that something has gone wrong).

[squidfunk]

The GitHub Actions workflow builds the site and pushes it to the gh-pages branch, which is then picked up by GitHub Pages for deployment. This is what Deploy from branch in the screenshot above is all about. Our documentation also talks about making sure that gh-pages is set as a branch (below the code block):

If the GitHub Page doesn't show up after a few minutes, go to the settings of your repository and ensure that the publishing source branch for your GitHub Page is set to gh-pages.

[nickriches]

Yes, in retrospect this makes sense. Thanks for help.