Python Sphinx css not working on github pages

Question

I have created documentation for a Django project using Sphinx and copy the content of html folder after executing the make html command into the docs/ folder of my repo and push it to Github. After that I have set this docs/ directory to Github Pages, now it's loading the documentation but the css is not working it's just a docs text with any styling.

Here's my Sphinx's config.py:

import os
import sys
import django
sys.path.insert(0, os.path.abspath('..'))
os.environ['DJANGO_SETTINGS_MODULE'] = 'PROJECT_NAME.settings'
django.setup()

templates_path = ['_templates']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
html_theme = 'bizstyle'
html_static_path = ['_static']
BUILDDIR = '.'

and here's the link to the docs page from GitHub pages: https://arycloud.github.io/Tagging-Project-for-Machine-Learning-Natural-Language-Processing/

what can be wrong?

None of the CSS or JavaScript loads. For how to fix it, you can post-process the HTML. — Steve Piercy, Dec 26 '19 at 10:59

score 16 · Answer 1 · answered Aug 25 '20 at 09:43

I've used sphinx/githubpages to document one of my python projects. I found this blog post very helpful. Here's an example of my working docs directory.

Adding a .nojekyll file in the docs directory will fix the issue. This tells github pages not to publish the files through jekyll. With this, you won't need to change any directory names and it should work with "_" prefixes.

score 6 · Answer 2 · answered Apr 11 '21 at 21:00

TL;DR

Add a .nojekyll file to the toplevel directory of your repository (source).

In contrast to previous answers, the .nojekyll file has to be on the toplevel - even if you serve your page from docs/.

Background:

Github pages uses jekyll by default. When jekyll generates a site, files whose name starts with an underscore are not included in the destination (source, bottom). This is why they are not served by github pages as long as you are lacking a .nojekyll (to disable jekyll processing).

Worked for me, but I added `.nojekyll` file to `docs/` and my github pages build was staring in `docs/` — Grzegorz Krug, Oct 04 '22 at 19:23

score 1 · Answer 3 · answered Apr 09 '23 at 18:56

1

There is a sphinx extension for github pages: sphinx.ext.githubpages

Appending this to the list of extensions in the Sphinx's config file docs/conf.py should do the trick.

...

extensions = [
    ...,
    "sphinx.ext.githubpages",
]

...

answered Apr 09 '23 at 18:56

Shashanka Prajapati

381
4
7

score 0 · Answer 4 · edited Jan 28 '20 at 17:33

0

I was doing the same thing; the issue is with the underscore in the folder name. The underscore means to ignore the folder.

I used sed to modify it.

edited Jan 28 '20 at 17:33

Das_Geek

2,775
7
20
26

answered Jan 28 '20 at 15:33

bertty contreras

1

score 0 · Answer 5 · answered Jan 05 '21 at 14:47

For me the issue was I used the Read the Docs theme and added it as the HTML theme:

html_theme = "sphinx_rtd_theme"

but I forgot to include it in the extensions:

extensions = [
    ...
    "sphinx_rtd_theme",
]

and import it:

import sphinx_rtd_theme

I was able to figure this out by looking at the console error messages and seeing what the issue was:

Python Sphinx css not working on github pages

5 Answers5

TL;DR

Background:

Linked