Step by step. Wherein our intrepid programmer embarks on the seemingly simple journey from a straightforward but boring and hard-to-maintain website written in raw HTML, to a shiny new website based on Jekyll and hosted on GitHub Pages. We’ll see how simple it really is in the next installment or two.
(Aside: it must be said that between a good editing mode in emacs and a good set of Makefiles, pushing content to the old site was never the issue. The real problem was the blasted sidebar, which had to be cut-and-paste-and-edited onto every new page. Most of the time, I just punted on everything below what was linked from the home page. And that was bad enough.)
Create the repository on GitHub.
Create a repositoy on GitHub with (in my case) the name ssavitzky.github.io
Make shared repo and working tree on my web host.
ssh savitzky.net cd git/web # all my website repositories live here. git clone --bare email@example.com:ssavitzky/ssavitzky.github.io.git cd ../../vv/web git clone ../../git/web/ssavitzky.github.io.git/
On my web host, bare git repositories live in
~/git, and working trees live
in corresponding directories under
~/vv. The web subdirectory of each one
is where websites live; their name is (usually) the domain name of the site.
Eventually I’m going to use the site on my web host as a staging area.
Make a working directory on my laptop
cd ~/vv/web git clone firstname.lastname@example.org:git/web/ssavitzky.github.io.git cd ssavitzky.github.io.git git remote add github email@example.com:ssavitzky/ssavitzky.github.io.git git remote set-head github master
At this point, a simple
git push will push to the bare repo on my web host,
git push github will push to github. Eventually I’ll set up a hook that
deploys to the staging tree whenever I push to origin. Maybe. It remains to
be seen whether I can get Jekyll running there; I may have to test the site on
my laptop. (Testing locally is trivial:
bundle exec jekyll serve.
Set up Jekyll
Now, this is where it gets a little complicated. The theme in question,
although we found it in a gallery of Jekyll themes, isn’t hosted on GitHub.
It also doesn’t have any Jekyll (liquid) templates in it – one might have to
index.html page into layouts. So it’s not really a Jekyll theme at
For that matter, it’s not entirely clear to me that I want my main site to be hosted on GitHub, so another possibility would be to add the template to my existing site. It’s really tempting to track down a command-line Liquid template expander and incorporate it into MakeStuff. One consideration that may be the deciding factor is that my current site includes my resume. Of course, I could build that offline.
Anyway, let’s proceed. If nothing else, I’ll get an article out of it.
In any case, there’s a lot of undocumented stuff involved in setting up a Ruby development directory. The quick-start guide says:
gem install jekyll bundler
But you also need
--user-install, and that says
gem install --user-install jekyll bundler WARNING: You don't have /home/steve/.gem/ruby/2.5.0/bin in your PATH, gem executables will not run.
By the way there’s a gem called github-pages that’s supposed to install the complete environment and keep it in sync with GitHub. It doesn’t work either. So…
gem install --user-install jekyll bundler bundle exec jekyll new --force --user-install . bundle install --path vendor/bundle bundle exec jekyll serve
At that point, you have a working (though empty) Jekyll site.
Making the pages I’ve already written (about-me, hire-me, and this article) show up in the navigation is mainly a matter of giving them YAML frontmatter.