CODEWITHSUNDEEP
htmlgithub-pages
Billy Peake
Billy Peake

Reputation: 51

Why won't Github Pages serve my documentation?

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!

Upvotes: 3

Views: 121

Answers (2)

Billy Peake
Billy Peake

Reputation: 51

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!

Upvotes: 1

Tallboy
Tallboy

Reputation: 13417

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

Upvotes: 0

Related Questions