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.
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 http://127.0.0.1:4000
bundle exec jekyll serve
Modify Makefile:
default: install
all: install build
.PHONY: install
install:
bundle install
.PHONY: upgrade
upgrade:
bundle update
.PHONY: serve
serve:
bundle exec jekyll serve --trace --livereload
.PHONY: build
build:
JEKYLL_ENV=production bundle exec jekyll build --trace
Modify .gitignore:
# jekyll
_site/
.jekyll-cache/
.jekyll-metadata
# sass
.sass-cache/
# bundler
.bundle/
vendor/
mainI 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
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
gist:
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
plugins:
# - 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
kramdown:
input: GFM
hard_wrap: false
gfm_quirks: paragraph_end
math_engine: mathjax # overridden
syntax_highlighter: rogue # overridden
syntax_highlighter_opts:
default_lang: plaintext
templage: '' # overridden
.jekyllOne 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.
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>.
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.
<ul>
{% assign pages = site.pages | where_exp: 'page', 'page.url contains "/notes"' | sort: 'name' %}
{% for page in pages %}
<li>
<a href="{{ page.url }}">{{ page.name | remove: ".md" }}</a>
</li>
{% endfor %}
</ul>
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.
Liquid template language. Shopify. Liquid template language.