Ah, Jekyll. What a terrible name for a great blogging tool. Jekyll blogs are typically faster, cheaper, and more secure than an option like WordPress. Plus, the writing experience is awesome:
What we’ll be using
Creating your blog
2. Open Finder. Inside your Documents folder, create a folder called GitHub.
3. Click into your new GitHub folder and find the Gear icon on top of the Finder window. Click it and select New Terminal at Folder.
4. Run the following command. It might take several minutes to complete.
gem install bundler jekyll
5. Now run
jekyll new your-blog-name (use the name of your blog).
cd your-blog-name (again, use the name of your blog).
git init to create a Git repository for your blog.
8. Open GitHub Desktop and add your blog’s folder:
- If you’ve never used GitHub Desktop, you won’t have any repositories yet. Click the button that says Add an existing repository from your hard drive and open your blog’s folder.
- If you’ve used it before, you can press
O(that’s the letter O, not the number zero) to add your blog’s folder.
9. Select every file, add a summary like “Created blog”, and press Commit to master in the bottom left. Then click Publish this repository to GitHub in the upper right.
Congratulations, you’ve set up your Jekyll blog! Let’s start working on it.
Viewing your blog in development
10. It’s much easier to work with your blog if you can look at it, so let’s spin up a local development server. Inside the terminal, run
jekyll s to spin up a local server for your blog. Then go to localhost:4000 to see your blog as you develop. (It looks pretty bare right now – we’ll write some posts soon.)
You can stop your server by pressing
C. (You might have to hit it twice depending on your setup.)
Editing your blog
11. Open your Jekyll blog in your text editor of choice. You’ll see that the folder structure is set up like this:
_posts/ # your posts _config.yml # your blog's settings .gitignore 404.html # what users see on your 404 page about.md # your about page Gemfile # your "plugins", so-to-speak Gemfile.lock index.md # your homepage
12. Let’s write our first post. Create a new file inside the _posts folder with the format
YYYY-MM-DD-name.md. (Most text editors allow you to right-click the folder name to create a new file.) For instance, I use Jekyll for this blog, and the filename of this post is 2019-10-10-jekyll.md.2
Paste this into the file and save it:
--- layout: post title: 'Your title' --- The body of your post goes here.
Here’s what’s going on:
- At the top of this post, we’ve added front matter in between two sets of dashes (
---). Front matter tells Jekyll that it should process this file. It gives Jekyll the meta information it will need to generate this page.
- At the very least, you should include a
titleon each post.
- Optionally, you can set a
permalinkto control the URL for this post. For instance,
permalink: jekyllwould place the post at yourblog.com/jekyll.
- You can add formatting to your posts with Markdown.
Let’s take a brief detour to talk about images.
Adding images to Jekyll
If you want to add images to your posts, I recommend creating an images folder at the top of your blog and creating a folder for each of your posts inside. For instance:
# Example of folder structure that supports images images/ └─ paris/ └─ croissant.png _posts/ └─ 2019-10-10-paris.md
--- layout: post title: 'My trip to Paris' --- In Paris, I had this delightfully buttery croissant: ![alt text goes here](/images/croissant.png)
Alternatively, you could use a service like AWS’s S3 to host your images. S3 would be a good option for image-heavy blogs with a lot of traffic because it will keep your costs as low as possible. But if you’re just starting out, you probably don’t need to worry about it.
Customizing your theme
Theming is a pretty intensive topic, so I won’t be covering it in this post. The good thing is that it’s not hard – it just requires creating some HTML and CSS files in different folders around your blog – but it can seem complex when you’re starting out.
Putting your blog live
What fun is having a blog if no one can read it? Let’s put our blog live so others can view it.
13. Sign up for a free hosting account at Netlify.
14. Connect GitHub and Netlify. When you go to configure your blog, you’ll want to use the following settings:
- Branch: master
- Dir: _site
- Build command: jekyll build
15. Your blog is now live on Netlify. The current URL is randomly generated, but you can add a custom domain if you’d like:
One of the nicest things about using Netlify is that your hosting is free for up to 100GB of bandwidth per month. This is one of the benefits of using Jekyll: because it’s so lightweight and easy to host, you immediately start saving money. If you’re interested in why it’s free, I’ll explain at the end of this post.
Updating your blog
Now that you’ve set all of this up, Jekyll becomes much easier to work with.
Edit your blog inside your text editor. When you want to publish your changes, just open GitHub Desktop, Commit your changes to master, then click Push origin. That’s all you need to do.
Netlify constantly watches your GitHub repository for changes and automatically rebuilds your blog when you push. Your changes will usually go live within the minute.
How Jekyll works
Jekyll is a “static site generator”, but that probably means nothing to you. So let’s contrast it with a dynamic site like WordPress. In plain English, this is what happens when you visit a WordPress website:
- You: Show me example.com/cat!
- WordPress: Hey Database, get the information for /cat!
- Database: Okay, here’s what I dug up.
- WordPress: Perfect. Let me just assemble this…
- WordPress: Done! Here you go, user!
The important part here is that WordPress works with a database to generate a page then hands it back to the user. This happens every. single. time. the page. is visited. If 100,000 people visit a post, WordPress is going to ask the database for that post and then assemble the page 100,000 separate times.
Jekyll, on the other hand, says this: “Let’s generate the post once, at build time, and then just hand everyone the same thing every time they ask.” That’s why they call it static – because it doesn’t change!
- You: Show me example.com/cat!
- Jekyll: Okay, here you go.
See how much less complicated that was? That’s why Jekyll is so cheap to host. It takes a fraction of the processing power and doesn’t require any fancy server-side software to run. It’s literally just files sitting in a folder somewhere.
Other benefits of Jekyll
- Static sites can stand up to insane amounts of traffic. For instance, Barack Obama’s campaign used Jekyll to handle 81,000,000 pageviews in 6 months.3
- Your site will be version controlled through GitHub, which means that you’ll have a record of all your content at the time of every push. You’ll have at least three versions of it “backed up” at all times: one on your local computer, one on GitHub, and one on Netlify.
- It’s much more cost-effective than options like WordPress. You’ll likely be able to host your blog for free.
- It is much more secure than WordPress. You can hack a database, but you can’t hack a plain HTML file! (Just be sure to protect your GitHub and Netlify passwords.)
- It’s easier to customize to your liking.
- You can choose whichever editor you want.
- There’s something cool about opening the terminal to work on your blog.
- Your posts will still be around in 100 years. Markdown is future-proof – it’s basically just a text file.
“[Plain text] is a standard format not owned by any company. It will be readable in 50 years on devices we haven’t even imagined yet.” - Derek Sivers
There you have it: a simple overview of setting up a Jekyll blog. If you were able to set up your blog with this tutorial, send me an email! I’d love to take a look.