Yet Another Github Pages Build Error Thread

Help
1

I have a fully functioning local site running on Windows with Jekyll 4 and the just-the-docs theme. The environment is built via bundler and dependencies are installed locally. I do not have/want the github pages gem installed, and I do not want to use the remote_theme config option on the live website. I want the local and hosted instances to be identical, so my workflow can be relatively automated.

Every time I try to deploy to Github Pages, I get a build time error saying the just-the-docs theme can’t be found. The theme is listed in the Gemfile and in the config.yml (as theme, not remote_theme), can anyone tell me what I’m missing?

I’ve read all of the Github Pages/Testing your GitHub Pages site locally with Jekyll documentation on Github, all of the Github Pages/Github Actions documentation on jekyllrb, the documentation specific to my theme, many posts here, and tried using @MichaelCurrin jekyll-gh-actions-quickstart template and Actions workflow because it utilizes the same theme, to no success. There are so many second and third party sources of information and instructions on how to deploy to Github, all with seemingly their own unique methods, that it’s difficult to keep track and even more difficult to implement for some reason. The site runs flawlessly locally though. Should I just push the _site folders static files?

2

I added a .nojekyll file to bypass Github’s automated building (I think?), let my workflow gh action do that, and changed my source branch to gh-pages. I have no conceptual understanding as to why this worked, but it did, and my site is (currently) live!

3

Think this was/is your issue. There is a small subset of 3rd party themes allowed by GitHub when using the theme config. This is done for security reasons as installing themes this way use Ruby gems and GH only allows ones that pass their requirements.

Installing a theme via the remote_theme configuration (if available) doesn’t have this limitation. Nor does using a GitHub action workflow to build/deploy your Jekyll based site on GitHub Pages.

4

The Jekyll theme docs mention this but it is buried and easily missed.

If you’re publishing your Jekyll site on GitHub Pages, note that GitHub Pages supports only some gem-based themes. GitHub Pages also supports using any theme hosted on GitHub using the remote_theme configuration as if it were a gem-based theme.

5

I was able to deploy without having to resort to using remote_theme, thankfully. Now my local and github environments are identical and I can instantly commit any edits I make locally to my repo :grin:

1 Like
6

Could you please share the exact steps? :slight_smile: How did you manage to do this?