With my blog now set up and all working, I figured I should document the process in case I ever need to re-do it. So here it is: How to create a blog using Jekyll and Netlify. Jekyll is a static website builder with a specific focus on blogs, and Netlify is a free static website host. Both projects offer amazing documentation so a lot of the steps below will mainly be linking back to specific parts of their docs - it’s not just me being lazy with the details, I swear!

Installing Jekyll

Obviously if you’re going to use Jekyll to generate your blog, you’ll want to have it installed first. They provide detailed installation instructions for Windows, MacOS and Linux here, so go do as they say and you should have Jekyll up and running in no time.

Creating the Blog

Again, Jekyll provides a quick start guide here on how to create the blog, but it can be summed up as running jekyll new myblog (where myblog is the directory it will create to hold everything) and then running bundle exec jekyll serve from inside the newly created directory. Now you should be able to see your blog up and running at http://localhost:4000. Congrats, you now have a blog so you’re pretty much halfway there… well, almost!

Modifying the content

Ok, I suppose having the blog isn’t much use if it doesn’t contain any of your content, so that’s the next step. You’ll need a text editor to change these files, I quite like Visual Studio Code but any one will work. First, open the _config.yml file inside the myblog directory. In this, modify the personal details (title, email, description…) to whatever you want.

Next up is the file called about.md, which is used to generate the about page for your blog. This uses markdown which gives you more control over the format of the generated page. (Protip: In VS Code, the key combination ctrl + k, v gives you a side by side view of the markdown you’re editing and the page it’s generating.) You can make any changes to this file, and they should be reflected when you refresh the about page in the browser (assuming bundle exec jekyll serve is still running from earlier).

Finally, it’s time to create a post on this new blog of yours. As nice as those default posts are, they’re probably not what you want to show to your readers. So inside the _posts directory, create a new file with a name matching the format used by the default posts (i.e. YYYY-MM-DD-name-of-post.md). There are some attributes describing the post (called Front Matter) kept inside triple dashes at the top of the file that Jekyll will look for. You can copy these from some of the default posts included by Jekyll or from here:

---
layout: post
title: Creating a Blog using Jekyll and Netlify
author: David Byrne
---

You’ll obviously want to customise them to suit your own post however. Beneath this, you can start writing the actual content of the post. When you’re happy with what you’ve written, you can refresh the browser window to see your new blog post.

Pushing to GitHub

Once you’re happy with what you’ve written, it’s time to begin the process of making your blog public. You can’t push your site to Netlify directly, so you’ll have to create a GitHub repo first and then let Netlify access that. Follow the GitHub instructions here to create a repo and upload your blog.

Publishing with Netlify

Now that you’ve got everything else set up, it’s time to publish the blog using Netlify’s free hosting. Visit www.netlify.com and link your GitHub account. Then select to create a new site and choose the GitHub repo containing your blog. Netlify should detect it’s a Jekyll site automatically and fill in the appropriate build instructions for you. Click to continue and Netlify will automatically build and deploy your blog. This should take less than a minute, after which Netlify will tell you it was deployed successfully and provide a URL to the site (eg. example.netlify.com). Visit this site and you should find your blog just like you previewed it locally, except now it’s accessible by the entire world! To make any changes or new posts, modify your files locally in the myblog directory, push the updates to GitHub and Netlify should automatically rebuild and deploy your new site.

And that’s it, you now have a blog that can be written using markdown, built using Jekyll and hosted with Netlify. There are a few extra, nice-to-haves that I added however, so take a look through the next few sections in case you want any of them on your blog.

Custom Domain

Although there’s nothing wrong with your blog being on example.netlify.com, it would look fancier to have it on a custom domain. If you don’t have a domain name already, you can buy one from Netlify and they’ll handle configuring everything for you. If you already own the domain you want to use, you’ll have to set it up with your DNS providers. This generally involves creating a CNAME record pointing blog.custom-domain.com to example.netlify.com, obviously using your own values there instead of the placeholders. Your DNS provider will have full instructions on how to do this. Inside the Netlify control panel, you can add and verify the custom domain you’re using, letting Netlify host your blog at that new address. After waiting a few minutes to let DNS changes propagate, you should be able to open blog.custom-domain.com and see your own blog.

HTTPS

There’s currently a big push towards every site being secure by default on the web. With major browsers moving towards marking HTTP sites as insecure, you’ll want to ensure HTTPS is enabled for your blog. Netlify provide HTTPS connections free of charge, including for custom domains, so you’ve no reason not to use it. If Netlify haven’t enabled it by default for your site, you can check a box in the domain management section of your settings to allow them to use HTTPS.

Disabling your old domain

Just when you thought you were done with messing about with domain names, surprise! Currently your site is available from both blog.custom-domain.com and example.netlify.com. If you want to ensure everyone only uses your custom domain and not your Netlify one, you’ll have to create a redirect. In the root of your myblog folder, create a file called netlify.toml. In that, add the following (except using your blog’s URLs instead):

[[redirects]]
  from = "https://example.netlify.com/*"
  to = "https://blog.custom-domain.com/:splat"
  status = 301
  force = true

This tells Netlify to redirect everyone from any page at your Netlify domain to the same page but at your custom domain. You can test it out by going to the Netlify domain in your browser and watch as you’re sent to the custom domain instead. Now you can rest assured everyone who reads your blog will see it at your fancy custom domain instead.

If you’re wondering why this section is down here and not up with the rest of the custom domain configuration, it’s because you have to specify the protocol (i.e. HTTP or HTTPS) in the redirect rule. If you didn’t have HTTPS set up and you put it in the redirect rule above, things would break and you wouldn’t be very happy with me. But it’s ok, that’s the end of all the custom domain configuration, I promise!

HTTP/2

HTTP/2 is a brand new version of the protocol the web runs on. The major browsers all require HTTPS to be used for HTTP/2 though so if you’ve skipped over the HTTPS section above, it might be a good idea to go back up there. HTTP/2 has a number of features designed for higher efficiency loading of pages, which in theory would allow your blog to load faster. The blog created by Jekyll is so light though, there’s probably no noticeable benefit of using it… but it’s a new thing, and I like playing with new things, so I did. There’s no real need for you to do anything though, unless you also like playing with new things, in which case you’ve come to the right place.

Most of the HTTP/2 features are managed automatically by Netlify, so you don’t have to worry about them. The big feature you do need to do something for is called “server push”. This allows servers to send extra resources to browsers before they ask for them, saving a round trip. This can be controlled by adding special headers to your HTTP/2 responses. Jekyll generates a main.css file that’s used by every page of the blog, so it’s an ideal use-case for server push. Open the netlify.toml file again and add:

[[headers]]
  for = "/*"
  [headers.values]
  Link = [
    "</assets/main.css>; rel=preload; as=style"
  ]

This states that for every request, Netlify should add the appropriate header telling them to push the main.css file to the client. You can quickly verify the server push is working by checking the network tab of your browser dev-tools, and looking for evidence it was pushed without the browser having to specifically request it. If you have nghttp installed, it’s easier to test using that by running: nghttp -ans https://blog.custom-domain.com. This should produce an output containing something like:

id  responseEnd requestStart  process code size request path
13    +607.47ms       +157us 607.31ms  200   1K /
 2       +1.25s *  +603.54ms 647.11ms  200   1K /assets/main.css

The * in the requestStart column of the main.css entry means the file was pushed without the client having to specifically request it, showing you’ve got it set up correctly.

Jekyll Plugins

Jekyll has a massive ecosystem of plugins that can be used to customise your site in countless ways. Chances are if you want to modify something about your blog, someone out there has already done it and published the plugin. Although some plugins may have more complexity in their set up, the main installation steps will be the same. We’ll take the jemoji plugin as an example to work through, which adds Slack and Github style emoji support to your posts.

Go to the jemoji releases section and find the latest version (0.10 at the time of writing). Then, in your Gemfile file, add gem "jemoji", "~> 0.10" inside the Jekyll plugins group section. Next, add - jemoji to the plugins section of your _config.yml file, telling Jekyll to use this plugin when building the site. Now, we have to actually install the plugin, which can be done by running bundle install. Since we have everything set up, we should be able to take advantage of this plugin to start adding emojis everywhere. Try adding :thumbsup: to a post, and then re-run bundle exec jekyll serve to preview your site. You should now see a :thumbsup: instead.

Plugins can be used to change the site’s theme, add multi-language support (i18n), support blogging formats other than markdown, improve SEO, minify assets etc. so go have a look at what’s available and I’m sure you’ll find a few to use for your blog.

Wrap-up

And that’s pretty much it. There’s much more you can do with Jekyll and Netlify but I’ve covered the most important features above. For anything else you want to do, I’m sure there are plenty of guides out there that’ll walk you through it. So go enjoy your new blog!