Problem with _mkdocstrings.css being 404 when deploying to GitHub Pages

[davep]

While experimenting with mkdocstrings for a personal project, I noticed that the locally-served result:

was looking very different from the result when hosted on GitHub Pages:

As you can see, some of the text is missing and some of the alignment is off. After digging a little into the console in the browser I noticed this:

What's confusing me is that I can see _mkdocstrings.css in the local gh-pages branch, I can also see it in the pushed branch, but if I try and get the file via some method it's coming up as 404:

Can anyone see anything I missing here? Is there some step I'm missing that will have the deployed version look as nice as the locally-served version?

If it helps, this is the current state of the configuration.

[pawamoy]

I don't think you're doing anything wrong. It feels like a browser/server cache issue. Have you tried force-refreshing the page?

[davep]

Given I was seeing it in the browser and also on the command line, and also in an unrelated repo where I'm playing with the same kind of setup, I sense it's not a browser cache issue. All other assets are fine, it's just this one particular file for some odd reason.

[pawamoy]

6 hours passed, still not working? Have you tried re-deploying the docs? I know I'm not very helpful but I just don't see why the server would send a 404 when the file was clearly present on the branch during deployment 🙂

[davep]

Oh, it's helpful! At least I know I'm not the only one confused by this. 😅

It's also the same file in two unrelated repos that's showing the exact same behaviour; I'm starting to wonder if this is some general issue with GitHub pages (eg: 404s on files whose name starts with an underscore).

I'll experiment some more today.

[davep]

Right, morning coffee had and back at my desk. On the off chance this might be useful for anyone else who runs into this (I hope this is some weird isolated issue, of course), here's a recap:

• I'm currently getting round to adding mkdocstrings to some of my Python-based repos; toying with 2 at the moment.
• I'm using gh-pages to host the documentation.
• In the two repos I've experimented with so far, for some reason assets/_mkdocstrings.css is showing 404 in any client despite being there in the gh-pages branch.
• Example 1:
  • It's in ngdb.py:gh-pages but is 404 in a client
• Example 2:
  • It's in textual-fspicker but is 404 in a client

[davep]

Hypothesis: https://www.ianwootten.co.uk/2022/11/08/how-to-use-underscores-with-github-pages/

[davep]

Confirmed. If I add .nojekyll to the root of the gh-pages branch in one of the problem repos (for example) then _mkdocstrings.css is no longer 404 and everything renders fine.

Now to figure out how to automate that...

[davep]

Just to double confirm, I made this change to the other repo that was seeing the same problem, then built and pushed the pages and it's all working as expected, _mkdocstrings.css can be seen and is doing its job.

[pawamoy]

How do you deploy? It might be that mkdocs gh-deploy adds this .nojekyll file for us, while other methods do not.

[davep]

Good point, I'm using ghp-import --push site (for no other reason that that's what I stumbled on as an approach to this). I think I thought that mkdocs gh-deploy was simply an alias for that, more or less. I wonder if it does do that.

I'll have to test this out on a fresh repo using that approach and see if .nojekyll magically appears.

[pawamoy]

ghp-import seems to provide this option, and that's what MkDocs uses: https://github.com/mkdocs/mkdocs/blob/4c7404485f988f409ccaf42fefe705222ff5965a/mkdocs/commands/gh_deploy.py#L138 🙂

[davep]

Ahh hah! Thanks, hadn't noticed this at all. All makes sense now.

[davep]

And, sure enough, there's this command line option too: -n, --no-jekyll