GitHub Pages doesn't deploy correctly

[spinningrachel]

Hi. I'm creating mkdocs and deploying to GitHub pages for the first time. My repo is public: https://github.com/spinningrachel/lightrun-mkdocs

I followed alllll of the instructions and just did some basic updates to the configurations - nothing fancy at all. Home is index.md in the docs folder. The documentation doesn't actually say if we should use root or docs ...

Here's the low-down:

• On a local build, everything is perfect and beautiful
• On the default root build, I get a 404
• On a build from docs, I get the landing page (index.md) but no templates or layouts so there's no nav bar or anything, and if I type in manually the url for a specific page, for example, I get a 404.
• Some of my trials included mysterious 403s also

Desperate for help.

[squidfunk]

Looking at your repository, it looks like you're using AsciiDoctor, not MkDocs. Other than that, if you want to set up MkDocs, please see the Getting started guide which explains all necessary steps from installation to deployment.

[spinningrachel]

@squidfunk I entered the wrong link accidentally. Since then though, I've updated this one as well - and this one also didn't work as well.
https://github.com/spinningrachel/lightrun-mkdocs

When set to master-docs:
If I add index.html to the suffix of the URL - then I reach the unformatted landing page with no navigation or anything:
https://spinningrachel.github.io/lightrun-mkdocs/index.html

The base URL leads to a 404.

When set to gh-pages-docs:
The base URL leads to the unformatted landing page with no navigation or anything:
https://spinningrachel.github.io/lightrun-mkdocs/index.html

The repo is definitely mkdocs now.

I finally figured it out l- setting it to gh-pages-root does work. But that's not documented anywhere on any of the pages or tutorials you or ReadtheDocs own or collaborate with. I've read all of them over and over and over again.

[squidfunk]

Thanks for the update. I haven't had any problems following the steps and examples in the docs. The GitHub Pages deployment works instantly with the GitHub Actions template listed in the documentation. I don't know what you mean by master-docs and gh-pages-docs – if you just create an empty repository and follow the steps, it will deploy to the gh-pages branch which is the correct one.

[spinningrachel]

What I mean is that, at least for beginners and for people who have used just Jekyll in the past (if I'm not mistaken) then you don't have to/or don't know you have to select gh-pages as the branch for publication in the repo settings, but for mkdocs you do - so it would be super helpful to document this explicitly.