How to use theme from github.io site for Github Project Pages sites

Question

I've been working on my website on and off for a couple years, learned a ton about JavaScript, CSS, HTML, Bootstrap, Jekyll, Travis-CI, and Github Pages in the process. (Long list is a major factor in why it's taken so long.)

I've discovered that if I push to (or have Travis deploy to) the gh-pages branch of a repo, it actually becomes a subdomain of my website. Examples: here, here, here.

This is pretty awesome, but those sub-pages end up feeling like they're not a part of the same website, because they provide no way to get back to the main page. I'd like them to include my navbar.

Is there an elegant way to do this?

Answer 1

Yesterday I finally went through and did what I theorized about in September. The result lives here now. This was not an easy process, despite the documentation trying to be helpful, because the intersection of Jekyll and GitHub pages is such a massively complicated opaque box, and ruby was unfamiliar to me. But ultimately it boils down to a few important steps and gotchas:

1. You're gonna need ruby and several packages. sudo apt install ruby should give you ruby (interpreter) and gem (package manager).

   • Gotcha 1a: The basics are left unexplained, so allow me: Ruby code comes in packages called gems, which are a lot like python packages. They're managed by gem or bundler rather than pip and hosted on rubygems.org instead of pypi. Much like in the Python world where everyone sings the praises of conda, everyone in the Ruby world sings the praises of bundler, which is itself a gem, one that you have to gem install because it doesn't come packaged with ruby like gem itself. I found bundler to be buggy; it hung when I tried to bundle install github-pages (more on github-pages later). Also, bundler relies on yet more configuration files called Gemfiles, which are the analog of the requirements.txt files pip can but doesn't need to ingest. Honestly who wants more of that clutter lying around for a small project with no complicated dependency tree? And who wants to have to bundle exec jekyll serve instead of just jekyll serve? Are you kidding me? Just use gem to install things, and skip the Gemfile. Much like pip, I find simpler is better.
   • Gotcha 1b: If you sudo apt install jekyll, you get an old version, like 3.1 or something. But Jekyll is a gem; you can and should install using the package manager. (But actually don't do this, because it comes as part of the github-pages gem, and the versions don't agree. More on that later.)
   • Gotcha 1c: Oh, what's that? You want to gem install jekyll (or even gem install bundler)? Yeah, sorry, I can't do that because there's some stuff missing, and here's a long printout about it. ...Google, Google... sudo apt install ruby-dev. Oh, sorry I still can't build. Here are some other errors. ...Google, Google... sudo apt install g++. Okay now it works. This process might be slightly different for you; point is setting up a ruby environment can be dicey.
   • Gotcha 1d: Oh what's that? Now you want to be able to call jekyll from the command line like you could if you just installed it with apt? Well, sorry, I'm gem, and some times I don't put jekyll on your path. If this happens to you, pay attention to where gem saves the gems, go find the executable within, and then create a symlink with sudo ln -s /path/to/jekyll /usr/bin/jekyll

2. Move assets, _includes, _layouts, and _sass from the site to a new repo. Done. Bam. You have a remote theme now. It really should be that easy, but...

   • Gotcha 2a: No one tells you that's the minimum viable product, so you have to start by understanding what remote themes are and how they work. According to canon, they're full-blown gems. When you reference one, Jekyll needs to go and fetch it before it can generate your site. The Jekyll documentation is all about coaching you on how to truly package up your theme as a gem and push it up to rubygems.org, which requires: (1) a rubygems account, (2) for your theme to contain an abstruse .gemspec file, the contents of which are not well explained. Keep reading for why this is irrelevant.
   • Gotcha 2b: You have to understand how GitHub Pages actually uses remote themes. On this topic GitHub is happy to tell you about adding remote_theme: user/theme-name to the leveraging site's _config.yml (Jekyll config), but they neglect to tell you upfront whether they're pulling in a gem from somewhere or what. Turns out they're using yet another gem called jekyll-remote-theme to pull the raw files directly from a repo, making the step of compiling and uploading a gem and having a .gemspec no one understands or wants to look at unnecessary. (Hooray.) benbalter's documentation for the remote theme gem itself is the only place I could find this information.
   • Gotcha 2c: Beware that because Pages is still on Jekyll 3.8.6, you don't have certain functionality on GitHub Pages that you might want, like being able to define site data in the theme's _config.yml. As a result, my front-matter-prepended .css containing a few Liquid tags that worked just fine as part of my unseparated site ended up with emptystring tag substitutions in the generated site. I ended up hard-coding some variables in the theme.
   • Gotcha 2d: Any other folders and files--not among assets, _includes, _layouts, and _sass--(I had one named theme containing stuff like my favicon.) don't get folded in to a theme gem or transported via the jekyll-remote-theme mechanism employed by GitHub. By carefully amending the .gemspec, you can include those files in a gem, but this method has no effect on the behavior of jekyll-remote-theme, so I ended up basically putting everything in assets.
   • Complaint 2e: Ruby Sass is apparently deprecated now? Why has Jekyll continued to use it for so long? I've still not encountered an example where it seems useful.

3. Put a _config.yml containing remote_theme: yourname/yourtheme in the root directory of the gh-pages branch of every repo for which you want the Project Pages rendered in your theme. No Gemfile, no nonsense. Just wait for it to deploy.

   • Gotcha 3a: Jekyll looks specifically for a page.html file inside _layouts to render readme contents. If you have a page.html, then you can add your head, navbar and other _includes stuff to it with Liquid tags no problem. If you happened to forget this file or think Jekyll could use post.html instead, well then you'd be wrong, and the theme isn't applied. Not sure whether default.html would work as a failover. In any case, GitHub pages with Jekyll is super brittle, and I'm honestly lucky to have discovered this without being blocked by it, because (1) I haven't seen any GitHub documentation to describe exactly which commands are being called to generate Project Pages, (2) you can't see the terminal output for the remote compilation process**, and (3), because you don't know what GitHub is doing, there is no way to replicate it locally to see warnings or error printouts--that is if Jekyll even warns you about this.
     **If there actually is a way to view this somewhere, please tell me. GitHub says: "When you push changes to your publishing source on GitHub, GitHub Pages will attempt to build your site. If the build fails, you'll receive an email at your primary email address. You'll also receive emails for build warnings. You can see build failures (but not build warnings) for your site on GitHub in the Settings tab of your site's repository." I did receive an email stating "The tag include_cached on line 15 in /_layouts/default.html is not a recognized Liquid tag.", but I don't remember which build this was for, and I can't find the failure recorded in the repo Settings anywhere.
   • Gotcha 3b: If you update the theme, Pages sites which use the theme aren't rebuilt to reflect the theme changes. You have to manually repush to the branch a site is built from to trigger a site rebuild. This is pretty easy for repos I've integrated with Travis-CI, because I can just go down the list rerunning the most recent builds, which culminate in pushes to gh-pages branches, which in turn cause Pages servers to rebuild. But for other sites, I have to either make some legitimate change or push an empty commit.

4. Add plugins: - jekyll-remote-theme and remote_theme: yourname/yourtheme to the _config.yml in your User Pages site.

   • Gotcha 4a: Local execution is confusing. benbalter's readme is pretty good, but the Usage section still assumes you're using bundler. If you're not, then gem install github-pages like you'd install any other gem. This gem is really a huge list of other gems Pages servers actually run to generate your static site, including the same versions of jekyll and jekyll-remote-theme. You'll want these so you can catch all subtle version or display bugs locally and have no surprises in the cloud. Finally, despite it not seeming to be necessary for actual deployment, for local execution you have to make sure to list jekyll-remote-theme as a plugin in your leveraging site's _config.yml. Otherwise jekyll serve errors.
   • Gotcha 4b: Local execution with a remote theme is broken--or at least it is for Jekyll 4.0.0. It works fine for Jekyll 3, which is what GitHub Pages servers use, which is why it deploys fine. If you get Jekyll with gem install jekyll rather than from the github-pages list, you might get errors as I did.

So basically it's not hard in hindsight, but getting there is a frustrating fiasco of flying blind with only overly verbose, disappointingly incomplete maps to guide you. I wish GitHub would show you the whole process of site compilation and deployment in some terminal, like Travis-CI does for builds. And I wish Jekyll weren't so complicated. There are too many features, and too many things fail silently.

I hope this research can help somebody else.

Answer 2

I haven't implemented this yet, so more to come as I do, but I think I've found the canonical solution and want to document it for myself.

All Github Pages sites have a theme. You can either:

1. Go to Settings -> Options -> scroll down to Github Pages and select a theme from the theme chooser. This is lame, because there are only a few default choices, and you don't get to customize the theme yourself to reflect the idiosyncrasies of your site. Nor do off-the-shelf themes allow you to use the navbar from another site.
2. Or you can add a _config.yml file to your project that github will try to read and follow when it generates your Github Pages site. Therein you can specify a theme, one of several whitelisted choices (a limited list), or a remote_theme, which can be created by anyone. This is great, because you can specify your own theme.

This means the way to have consistent navbar and theme and everything across the User Pages Site and all my Project Pages Sites is to tease out my theme from the User Pages Site into its own repo and then reference it from all those other sites in config files.

Sounds like a chore, but it helps improve reuseability for sure.

I may also need to specify index.md in the top level of each project, to supplant the readme as the homepage and ensure content like <head> stuff and navbar make it in.