We installed jekyll with just-the-docs theme for our FreightForward Doc Software documentation site.

Upon github-pages deployment, we found the site to be blank. So it was obvious that github-pages build failed with jekyll errors.

Unfortunately the github-pages jekyll error debug section doc didn’t help much, if not at all! So we had to recheck our code and jekyll config along with googling for users with similar issues.

Upon our inspection on our code and config, we noted some issues.

_config.yml values

Check the keys value in _config.yml file.

theme, remote_theme

just-the-docs is not officially available for github pages. So along with the theme key in _config.yml, we need remote_theme key also.

remote_theme: pmarsceill/just-the-docs

base_url, url

in local testing of jekyll(jekyll serve), base_url is empty mostly.
For github pages, value to be in this format: https://.github.io, e.g., https://freightforward.github.io.
`url` is the repo name, e.g., `docs`.

baseurl: "/docs" # the subpath of your site, e.g. /blog
url: "https://freightforward.github.io" # the base hostname & protocol for your site, e.g. http://example.com

So the full url of the github-pages site is https://freightforward.github.io/docs

repo_owner_username: Your github account username for most cases. When the repo owned an organization in your github account, username will be that organization username, not your account username!

Jekyll errors

Check for any errors or warnings thrown when you run your site locally, i.e., jekyll serve.
There could be warnings and the site would still work locally but fail in github-pages build.

Directory Structure

Our site had pages grouped by a directory structure.
There was a top level directory named docs under which there were some pages markdown files.
|…
|— docs/ (index.md, page1.md, page2.md etc)
|— _config.yml
|— Gemfile
|…

In local testing, base_url was empty, but for github-pages its value set to be /docs.
So the local site url was like http://127.0.0.1:4000/docs, remember the trailing /docs in that url comes from our directory structure.
So for github pages build docs comes two times in the url, one is from the repo name, another is from our site structure directory.
A potential clash was impending. (We are not 100% sure though)
So we changed the directory structure just to be on safe side(As we didn’t have debug time at that moment)

Ide autoformatting

We used a jetbrains ide with markdown support, and we used to [reformat code][reformat_url] a lot.
In fact, hitting Ctrl+Alt+L was very frequent.
This worked well mostly, mostly!
It messed the formatting yaml front matters, which in turn makes the page un-renderable for jekyll. Beware!