Why won't Github Pages serve my documentation?

Question

I use sphinx to build html documentation, and am in the middle of open-sourcing some of my company's private repos.

Internally, we serve documentation from an S3 bucket through Cloudfront so we can put access controls in front of it. But for open source, I figured publishing via Github Pages would be the path of least resistance.

However, I cannot get the service to work correctly.

Here is my repo, with my index.html in the /docs folder.

Here is the site, which is not applying any of the linked css, and with all page links broken.

I tried to isolate the issue by making a test repo with just the built documentation, and publishing from master.

As you can see, this one does not even try to serve the index.html, I just get a 404 page.

These files work both locally and when serving from AWS, so I'm a little at a loss for why Github Pages is not serving it correctly. I feel like I must be making some sort of dumb oversight. If anyone with more experience could take a look and point me toward the error of my ways I would really appreciate it. I'm a backend engineer for the most part so website logic is a little outside my normal wheelhouse. Thanks in advance!

Billy Peake · Accepted Answer · 2020-02-25 00:57:21Z

1

To anyone else running into the same thing, I figured it out. Because I am pre-building the site in my CI/CD pipeline, I don't need jekyll to build the site for me, and need to add an empty config file for it.

From [here][https://www.docslikecode.com/articles/github-pages-python-sphinx/]:

Next, you set up the .nojekyll file to indicate you aren’t using Jekyll as your static site generator in this repository.

Thank you for your help!

answered Feb 25, 2020 at 0:57

Billy Peake

511 silver badge2 bronze badges

Sign up to request clarification or add additional context in comments.

Comments

Tallboy · Accepted Answer · 2020-02-25 00:55:09Z

0

You need a _config.yml, and you need to enable github pages on Master for the repo (go to settings). After that, you also need a Gemfile it the following:

source 'https://rubygems.org'

gem 'github-pages'

Normally, the GitHub pages site needs to be in the root, and yours looks like it's in a /docs folder, so I'm sure you can Google how to do that. It might not be possible though with GH pages, I'm not sure.

If it must be a subfolder and not the root of the project maybe something like this would work: https://gist.github.com/cobyism/4730490

Heres whats in my _config: for barebones sites:

permalink: pretty
sass:
  sass_dir: _scss
  style: compressed

I'm sure you can leave sass out

edited Feb 25, 2020 at 0:55

answered Feb 25, 2020 at 0:37

Tallboy

13.5k13 gold badges96 silver badges193 bronze badges

4 Comments

Billy Peake Over a year ago

Thanks for the response. Github Pages has a "Publish from master/docs" option that is supposed to be for exactly this use case. I will see if adding the config and gemfile help. It's weird that isn't mentioned at all in their overview.

Tallboy Over a year ago

let me add what goes in config at a minimum

Billy Peake Over a year ago

I figured it out. I needed to add a blank ".nojekyll" file to the "/docs" directory. Since I am pre-building the site and just need it to be served, the jekyll build was messing it up. Thank you for your help.

Billy Peake Over a year ago

Added it to the top-level answer, but can't accept my own answer for two days haha. Oh well.

Collectives™ on Stack Overflow

Why won't Github Pages serve my documentation?

2 Answers 2

Comments

4 Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

Comments

4 Comments

Your Answer

Sign up or log in

Post as a guest

Related