Hello again, Jekyll

I recently started working with Github Enterprise and have an internal website at work. Unfortunately it is quite restricted and I can’t run workflows, so I’m stuck with classic Jekyll.

I decided to consolidate my efforts and temporarily return my website back to Jekyll.

Install Jekyll

Create a Gemfile and run bundler and jekyll:

# create Gemfile
echo "source 'https://rubygems.org'" > Gemfile
echo "gem 'github-pages', group: :jekyll_plugins" >> Gemfile

# install gems
bundle install

# build and serve on
bundle exec jekyll serve

Modify Makefile:

default: install

all: install build

.PHONY: install
	bundle install

.PHONY: upgrade
	bundle update

.PHONY: serve
	bundle exec jekyll serve --trace --livereload

.PHONY: build
	JEKYLL_ENV=production bundle exec jekyll build --trace

Modify .gitignore:

# jekyll

# sass

# bundler

Aside: Rename main branch to main

I never did this with this repo. Let’s do it now.

# create main branch locally, taking the history from master
git branch -m master main

# push the new local main branch to the remote repo (GitHub) 
git push -u origin main

# switch the current HEAD to the main branch
git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main

# change the default branch on GitHub to main
# https://docs.github.com/en/github/administering-a-repository/setting-the-default-branch
# For me this is https://github.com/hparra/hparra.github.io/settings

# delete the master branch on the remote
git push origin --delete master

Enable Github Pages

Turn on Github Pages

Add _config.yaml

Copy Jekyll’s default _config.yaml:

pbpaste > _config.yml

If you build and push to Github you will notice some things break because these are Jekyll’s defaults, not necessarily the defaults that Github Pages uses.

It’s best to comment out the default config.

# github's default configuation
# https://github.com/github/pages-gem/blob/master/lib/github-pages/configuration.rb

# plugins_dir is overridden
# whitelist is overridden
jailed: false # overridden remotely
safe: true # overridden
lsi: false # overridden 
highlighter: rogue # overridden
  noscript: false # overridden
future: true

# default theme on both Github.com and Enterprise is jekyll-theme-primer
theme: 'jekyll-theme-primer'

# Combined list of PLUGIN_WHITELIST and DEFAULT_PLUGINS with difference commented out
# https://github.com/github/pages-gem/blob/master/lib/github-pages/plugins.rb
  # - jekyll-avatar
  - jekyll-coffeescript
  - jekyll-commonmark-ghpages
  # - jekyll-default-layout
  # - jekyll-feed
  - jekyll-gist
  - jekyll-github-metadata
  # - jekyll-include-cache
  # - jekyll-mentions
  # - jekyll-octicons
  - jekyll-optional-front-matter
  - jekyll-paginate
  - jekyll-readme-index
  # - jekyll-redirect-from
  - jekyll-relative-links
  # - jekyll-remote-theme
  # - jekyll-seo-tag
  # - jekyll-sitemap
  - jekyll-titles-from-headings
  - jemoji

# Github's default markdown settings
markdown: kramdown
  input: GFM
  hard_wrap: false
  gfm_quirks: paragraph_end
  math_engine: mathjax # overridden
  syntax_highlighter: rogue # overridden
    default_lang: plaintext
  templage: '' # overridden

Move everything to .jekyll

One of the things I never liked about jekyll were the folders starting with underscore. I also didn’t like those folder at my root directory.

source: .
destination: .jekyll/_site
layouts_dir: .jekyll/layouts
data_dir: data
includes_dir: .jekyll/includes

While the config allows me to move and rename some of these, I still can’t make another folder the site root. It seems source solves this use-case, but github overwrites this, and if you choose to build from docs in github settings, the expectation is that all the other jekyll-related files/folders are in there too.

Copy over the default templates

Github (Public and Enterprise) uses jekyll-theme-primer as the default theme. I prefer having my own copies so I can customize them.

curl -o .jekyll/layouts/default.html https://raw.githubusercontent.com/pages-themes/primer/master/_layouts/default.html 

Now I can remove that perpetual <h1>.

Restore my indices

When I used the original gliki I had a nice index based on my git history. Jekyll makes this difficult because I cannot get a list of pages in a directory directly from site. There may be a way to do this with collections, but this is where things start feeling hacky.

{% assign pages = site.pages | where_exp: 'page', 'page.url contains "/notes"' | sort: 'name' %}
{% for page in pages %}
    <a href="{{ page.url }}">{{ page.name | remove: ".md" }}</a>
{% endfor %}

Note in this example I didn’t remove README.md from the listing. It’s not clear how I would do that easily as there is not inverse of contains. I also needed to use the raw tag in that last code example, or else jekyll still interprets it!


That took longer than expected, but I got this website updating again. I’ve already come across a few things I want to change, but it seems better to work with same constraints that I have professionally. This way effort in either will benefit the other.


pages-gem/github-pages.rb at master · github/pages-gem. null. GitHub.

Jekyll. Michael Currin. Code Cookbook. Found this looking for good ol’ rake solutions but i think staying with Makefile is way to go. Thanks Michael.

gitignore/Jekyll.gitignore at main · github/gitignore. null. GitHub.

5 steps to change GitHub default branch from master to main. Steven Mortimer. stevenmortimer.com. Thanks Steven.

Configuring a publishing source for your GitHub Pages site - GitHub Docs. null. GitHub Docs.

Default Configuration. null. Jekyll • Simple, blog-aware, static sites.

github/pages-gem: A simple Ruby Gem to bootstrap dependencies for setting up and maintaining a local Jekyll environment in sync with GitHub Pages. null. GitHub.

Liquid template language. Shopify. Liquid template language.