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?
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:
You're gonna need ruby and several packages. sudo apt install ruby should give you ruby (interpreter) and gem (package manager).
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.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.)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.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/jekyllMove 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...
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.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._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.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.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.
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.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.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. Add plugins: - jekyll-remote-theme and remote_theme: yourname/yourtheme to the _config.yml in your User Pages site.
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.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.