By: Simon Goring
Table of Contents
- The Motivation
- GitHub Pages
- Choosing Jekyll
- Creating a Jekyll-based Website
I’ve become acutely aware that a blog is only really useful so long as it is continually updated. Once it starts getting stale then it becomes a liability. It looks abandoned.
So, I wanted to redesign my website, I wanted to be able to add some of the interactive documents I’ve been developing, and I wanted a bit more control over the site.
So let’s start with GitHub pages.
Anyone with a GitHub account has access to a GitHub page. Setting one up means that you can have an
http://username.github.io website, but you can also redirect a URL that you own to your GitHub page. GitHub maintains good tutorials, both on the basics of a GitHub page and also on redirecting to a custom domain.
GitHub pages can be as simple as a single
index.html page, or as complex as you want. So long as the site is ultimately served up as HTML you’re good to go. So, how do we build a webpage?
Conditions for a Back-End
I have a few conditions, and needs. In particular I’ve been using RMarkdown a lot lately. I have been generating tutorials directly in RMarkdown, but also rendering some to HTML to take advantage of some of the
d3.js applications that have been ported to R (the nice networkD3 package for example). Most of these just live in my GitHub repository, either rendered or raw, but I’d like to be able to serve them up in one place, so, condition one:
1. Must support HTML and Markdown
I’m not great at HTML, and I generally find editing it directly really frustrating. When pages start getting complicated I’ve totally screwed pages up and have basically had to abandon my plans. It’s partly a function of the fact I’m not a web developer, but it’s also a function of the fact that HTML’s markup is so extensive. I want a clean palette to edit while still being able to customize my site & documents.
2. Documents must be plain text as much as possible, but still be extensible.
I also want something that’s going to be supported fairly widely, that’s open, and that I can (theoretically) contribute to.
3. Must be open source.
It should be fairly obvious that, at this point, Jekyll seems to be the best option for me. Maybe there’s a bit of post hoc justification here, but in general I think I’m happy with my conditions.
How Jekyll Meets the Conditions
Must support HTML and Markdown Jekyll uses a back end that supports both Markdown and HTML. With a little bit of configuration it can support multiple different types of Markdown (the default is kramdown, but it can also support redcarpet and others). I’ve ported some
Rmd documents over and didn’t really notice any issues, but in general RMarkdown uses a pretty basic Markdown standard compared to others.
Documents must be plain text but still extensible
Creating a Jekyll-based Website
First, create a repository on GitHub to house your Jekyll website. If you’re going to use GitHub pages then you will create a repository called
USERNAME is your own username. Make sure to include a
License (I like the MIT License) files. You can also include a Jekyll
Once you’ve done this, clone the empty repository to wherever you’ll be editing the documents locally (on your computer), navigate into the folder and generate a new Jekyll site (make sure you follow the setup instructions here first!)
cd GitHub git clone https://github.com/SimonGoring/simongoring.github.io cd simongoring.github.io jekyll new . --force
--force flag stops you from getting a conflict error (the directory
exists and is not empty.) when you’ve been a responsible citizen and started your directory with a README and License file.
Even if you only get this far you can build & serve the website for the first time, and then
push to see your glorious template website live online:
$ jekyll build > Configuration file: C:/Users/XXXXXXXX/Documents/GitHub/USERNAME.github.io/_config.yml > Source: C:/Users/XXXXXXXX/Documents/GitHub/USERNAME.github.io > Destination: C:/Users/XXXXXXXX/Documents/GitHub/USERNAME.github.io/_site > Incremental build: disabled. Enable with --incremental > Generating... > done in 2.082 seconds. > Auto-regeneration: disabled. Use --watch to enable. $ git status > On branch master > Your branch is up-to-date with 'origin/master'. > > Untracked files: > (use "git add <file>..." to include in what will be committed) > > .gitignore > _config.yml > _includes/ > _layouts/ > _posts/ > _sass/ > about.md > css/ > feed.xml > index.html > > nothing added to commit but untracked files present (use "git add" to track) $ git add --all $ git commit -m "Generated my Jekyll-based website and built it for the first time!" $ git pull > Already up-to-date $ git push
And now, if you navigate to
http://USERNAME.github.io you’ll see your pretty website!