I Wanted a Blog

There are a lot of reasons you might want to create a blog. I wanted a way to share my ideas with others and sometimes I communicate more effectively in writing (and pictures) than speaking out loud. I also thought I could use it as a personal knowledge base to document past work on some of my projects. The inspiration came in part from a great KringleCon talk by Jack Rhysider, whose podcast (Darknet Diaries) I enjoy quite a lot. It seemed appropriate that my first post should be about creating this blog.

I Wanted Security

In the past I have used several wiki or other website packages to host KBs and other content via a cpanel-based hosting provider. My work style tends to involve putting a bunch of effort into a project, then moving on to something else, and sometimes returning to it. In my previous efforts, I didn’t do a good job of updating those software packages regularly, which inevitably lead to some form of hijacking. This time I wanted to use a framework that would allow dynamic content editing but “pre-compile” all the content so a static site would be served in the end. That is to say, the website would not contain any functionality to make edits to itself. Additionally, I wanted a cheap way to host the site reliably.

My Solution: GitHub Pages + Jekyll

One of the first options that caught my attention was GitHub Pages. It’s great because it’s free, super reliable, and it allows you to create content in Markdown and manage it as a git repository of text files. GitHub advertises the static site generator Jekyll as an easy way to create a beautiful blog using GH Pages.

A Confounding Number of Options

Every source I came across asserted that using GH Pages with Jekyll was an extremely easy way to start a blog, and each one recommended a totally different way of doing this. It threw me off because it felt like most of these sources must be wrong since they seemed to offer conflicting information. The truth is, there are so many ways to use GH Pages and Jekyll together that it is almost impossible to make it not work. The most confusing part was figuring out which method was right for me. I’m going to outline two different approaches in this post that are very different from each other. Hopefully it will provide a foundation even for those whose method of choice is somewhere in the middle.

Essential Reading

There are a few resources that most of the content of this post are drawn from. You will probably need to read at least one of them if you want to customize your blog over time. I try to breeze over material that these documents cover well. They are not prerequisites but you may want to refer to them while working through the methods I outline, or afterwards.

  1. The GitHub Pages documentation for Jekyll (which I think is more helpful that the Jekyll documentation)
  2. The Jekyll documentation
  3. GitHub Pages documentation

A Few Fun Facts

  • Jekyll is a program written in Ruby that will compile your Markdown blog posts into a template-based site (they’re called “themes”).
  • You can edit the theme.
  • You can use other people’s themes.
  • GH Pages will serve whatever content is in the “publishing source” of the repo (Markdown, HTML, etc).
  • The “publishing source” can be a folder (including /) or a branch (it is configured in the GH Pages settings panel for the repo).
  • GitHub will compile your Jekyll site for you if you commit the source files.
  • Only paid accounts are allowed to use GH Pages with a private repo.
  • GitHub allows you to edit and commit text files in your repos online.

A Few Important Implications

  • If you don’t want people reading the source files for your Jekyll site, you either need to upgrade to a paid GitHub account, or you need to commit only the compiled site files.
  • If you fork someone else’s Jekyll site or template, it becomes your Jekyll site.
  • In the simplest case, you can create and manage your entire blog through GitHub, with no code or content on your personal device (i.e. you could do the whole thing with a Chromebook or tablet).

The Simplest Case

With almost no effort or finesse, you can create a Jekyll blog by forking a template and adding and editing content on GitHub. There are a few reasons I don’t like this method, but I think it would work fine for a lot of people. Especially if you are a paying GitHub customer and are allowed to use GH Pages within a private repo. In this case you can store all your source files in the repo without making them publicly available and your site will still be served properly.

The default Jekyll theme is called Minima. Since the most recent version is in the main branch of their GitHub repo, you can fork that to use as the basis for your blog.

Fork Minima
The Minima GitHub repository
  1. Fork Minima and name the repo username.github.io where “username” is replaced by your GitHub username.
  2. In the settings for your new repo, navigate to the “Pages” tab.
  3. Under “Source” select the master branch and the root directory.
  4. Click “Save”.
  5. After about a minute you should be able to navigate to https://username.github.io/ and you will see the barenones Minima template content.
  6. The README.md file contains instructions for installation (which this method circumvents) and customization (most of which involves editing the _config.yml file).
  7. You will want to clear out or repurpose the post files in the _posts folder. Each post must be named with the publish date in YYYY-MM-DD format and a hyphenated title.
  8. Navigate to the _posts directory and open 2016-05-19-super-short-article.md as an example.
  9. Click the pencil icon to edit and modify the contents.
  10. Commit the changes and wait another minute before refreshing https://username.github.io. You will see the changed article in the table of contents.
  11. There is likely a lot of other content you would want to clear out or customize in the repo as well, but as you can see, it doesn’t show up in the site. One thing I don’t like about this method is that it feels very messy with extraneous files intended for template development (such as the README.md) that you just don’t need. The only files included in the Jekyll skeleton are:
    • 404.html
    • about.markdown
    • _config.yml
    • Gemfile
    • index.markdown
    • _posts
  12. Edit about.markdown to say something about you and your blog.
  13. Editing the _config.yml file allows customization of title, description, social media links, color theme, and many other aspects of your site. It is well commented and documented. Try changing the “title: “ and then view the changes.
Edit Config
The default _config.yml file

That is basically it. It’s a messy method, but you can have a decent minimalistic blog in about 10 minutes. There are many themes available for Jekyll that may work better or worse using this method. And of course, you can take steps to clean up the mess as you feel like it.

The More Nuanced Case

The method I prefer involves maintaining two repos, one public and one private. The private repo contains the source files and the public repo is used for the compiled site. Jekyll is run locally to compile the site and the output is pushed to the public repo. One advantage to this method is that it could be used with any hosting provider, while the previous method only works with GH Pages. Another advantage is that it prevents the source files from being available publicly.

Getting Set Up

  1. If you are not a regular git user, you will need to install and configure git, and create a GitHub account. GitHub has a good getting started page that should help.
  2. Install Ruby and Jekyll by following the OS-specific instructions provided in the Jekyll documentation.
  3. Create a private repo in GitHub to store the source files (call it whatever you want, I will refer to it as “blogdev”).
  4. Create a public repo named username.github.io where “username” is replaced by your GitHub username.
  5. Note: You will not be able to enable Pages until you have committed some files.

Creating a Site

The os-specific instructions here will be useful if you can’t use the Linux commands I give below, but I would skip everything before step #7 under “creating your site”.

  1. Clone the empty, private blogdev repo to an appropriate place on your computer.
    • git clone git@github.com:username/blogdev.git
  2. Move into the folder and initialize a new Jekyll site.
    • cd blogdev
    • jekyll new --skip-bundle .
  3. Find the latest supported version of the github-pages gem here (227 at time of writing).
  4. Edit the Gemfile to comment out the line gem "jekyll" and add a line below it gem "github-pages", "~> GITHUB-PAGES-VERSION", group: :jekyll_plugins where “GITHUB-PAGES-VERSION” is replaced with the version number from above.
  5. Save the file and then run Bundler to install Ruby dependencies.
    • bundle install
  6. Test site locally.
    • bundle exec jekyll serve
    • Navigating to the local site (probably http://127.0.0.1:4000/) should display a generic Jekyll site.
  7. Commit and push the generic site to GitHub.
    • git add -A
    • git commit -m "Initial Jekyll site source files"
    • git branch -M master
    • git push origin master

Customizing a Site

If you are using a theme (such as the included Minima theme) most of the customization will be done by editing the _config.yml file and creating new posts in the _posts folder. Themes are somewhat confusing in terms of implementation. They are intended to live outside of the source files for your site, and the content of the theme is included in the site during compilation. To override any theme-specific setting, you have to copy the appropriate file from the theme location into your site source files and modify it (Jekyll prioritizes the copy during compilation). Themes can be downloaded locally or referenced via GitHub repo. They can be made available as Ruby gems using Bundler, via git, or other methods. Most templates contain instructions explaining various customization options. Here, I update to the latest version of the Minima theme by referencing the GitHub repo. I could use the same repo via the remote_theme option, but I prefer to have the theme files downloaded and updated when I choose.

  1. Edit Gemfile, comment out #gem "minima", "~> 2.5" and add a line gem "minima", github: "jekyll/minima"
  2. Save the file and run bundle update to download the updated theme.
  3. The theme will be downloaded somewhere in your userspace which you can determine using bundle info --path minima
  4. Overwrite your _config.yml with the new Minima default with cp `bundle info --path minima`/_config.yml ./
  5. Edit _config.yml according to your best judgement (it’s well commented). The README included with the theme explains most of the settings.
    • Note that the setting to enable skins is not included by default.
  6. You can run bundle exec jekyll serve again to see how it looks.
  7. Edit about.markdown to say something about you and your blog.
  8. If you use this procedure with a different theme, the README may list other default content you should edit.
  9. Then push another commit of your customized source files.
    • git add -A
    • git commit -m "Updated Minima theme and customized config"
    • git push origin master

Creating a Post

Posts should be created in the _posts folder. Each post should be a Markdown file with a filename like “YYYY-MM-DD-title-of-post.markdown”. When Jekyll compiles the site, it uses the date from the filename in a variety of ways related to the date of the post and location of the source files in the directory structure of the site.

Each post should begin with a section of “front matter” which is a YAML block that defines metadata for the post such as layout, author, and category. Different themes use front matter in their own way, and usually contain sample posts to demonstrate their use. In particular, the layout options can vary quite a bit between themes.

Front Matter
An example of front matter

The Jekyll documentation for posts and front matter is pretty extensive, so I would recommend reading that to understand the options available. Your _posts folder should contain a sample created by Jekyll with the current date. If you edit the filename and contents to create a test post, and then run bundle exec jekyll serve again, you should see the modified post appear. You can duplicate that file and create additional posts and those will also show up when you compile the site.

Adding Images

If you’re making a blog, you will probably want to add images. The best way to do this is by creating a new directory to contain them inside the blogdev directory. From there you can create additional directory structure if you want. Each image can be linked from the post files by referencing the blogdev folder as the root of the file system.

  1. Create a directory to store images in.
    • mkdir assets (if it doesn’t already exist)
    • mkdir assets/img
  2. Put an image file in the folder via copy / paste or however you want.
    • wget http://toastytech.com/evil/billagram2.gif -P ./assets/img/
  3. Add a reference to the image to one of your sample posts.
    • ![Test image](/assets/img/billagram2.gif
  4. Rebuild the site with bundle exec jekyll serve and browse to the local URL to confirm the image is displayed.

Publishing the Site

When you compile the site by running bundle exec jekyll serve or bundle exec jekyll build, the resulting website is stored in the _site folder. The contents of this folder is the only thing you need to store in your public repo for GH Pages to publish your site. If you browse the directory structure you will see that it looks similar to that of the source files, but different. If you want to choose a different destination for the Jekyll output, you can do so like bundle exec jekyll build --destination <destination/path/>.

Depending on your OS and git client, you will likely need to use slightly different commands, but this is the general method for publishing your site.

  1. If you haven’t built the site already, run bundle exec jekyll build within the blogdev directory.
  2. Change into the _sites folder
    • cd _sites
  3. Initialize it for your public repo and push the contents
    • git init
    • git add -A
    • git commit -m "test publish to GH Pages"
    • git branch -M master
    • git remote add origin git@github.com:username/username.github.io.git
    • git push -u origin master
  4. Wait a minute or so and then browse to https://username.github.io and you should see your Jekyll site, including the posts you modified.

Continued Use

The basic idea for continuing to build your site is to add more posts, customize your theme, etc. and continue pushing modified source files to the private repo. When you’re ready to publish a change to your site you can run bundle exec jekyll build to build the site locally. Then change to the _site directory, and push the updated site to your public repo.

As mentioned above, any time you want to override a theme setting, you need to copy the file from the theme source to the approriate location in your blogdev folder, and then modify it. The bundle info --path minima command is very useful for locating the theme files if they reside on your computer. If you’re using the remote_theme option, you will need to download files from the theme’s GitHub repo as necessary. More on customizing and creating Jekyll themes can be found in the Jekyll documentation

Variations on a Theme

As I mentioned before, there are lots of ways to use Jekyll on GH Pages successfully. Bits and pieces of the two methods above can be combined in different ways, for example. Here are some small variations that might be helpful.

Using Remote Themes

Themes that are hosted on GitHub can be referenced directly in the _config.yml file without ever downloading them locally. In The More Nuanced Case, we modify the Gemfile and use bundler to get the latest Minima code from GitHub. Instead, we could leave the repo out of the Gemfile, and instead edit _config.yml to replace the line theme: minima with remote_theme: jekyll/minima. This will include theme content from the github repo each time the site is built. If you are committing your source files to a public repo and having GitHub build your site, everything should work automatically. If you are building the site locally, you will need to have the github-pages gem included in your Gemfile as previously described.

Fork Theme to Private Repo

A middle ground method that might be useful would be forking a template to a private repo, then cloning it and building your site locally, and uploading the compiled site to your public repo. You would still need to set up git, Ruby, and Jekyll on your computer. It might avoid some snags involved in working with templates. This also highlights that you can start a blog using The Simplest Case, wait until you have built some momentum, and then transition to The More Nuanced Case for a long-term strategy.

Closing Thoughts

It would be great if GitHub and / or Jekyll would provide a repo you can clone that contains the base skeleton files for a Jekyll site and a _config.yml file that includes remote_theme: jekyll/minima. Then you could create a proper site without needing to install Jekyll at all.

Writing in Markdown can be frustrating at first if you are used to a normal word processor (like most people). Using a text editor that has a good Markdown preview mode makes it a lot easier. I use VSCodium, which is the open source version of Visual Studio Code. I also found the article How writers can get work done better with Git, by Seth Kenlon very helpful for the less technical aspects of blogging in Markdown.

There is a lot to know about GH Pages and Jekyll. You should definitely continue reading about how to use GH Pages and Jekyll beyond this article. Hopefully this article will help someone get started in less time than it took me.

If you found this helpful or have suggestions for improvements, hit me up on Twitter or via email and let me know. Thanks for reading!