How to set up a Jekyll blog on Mac

Jekyll is a minimalistic blogging tool that generates faster, cheaper, more secure blogs than WordPress. It's completely customizable, and the writing experience is awesome:

This post will walk you through the process of setting up a Jekyll blog on Mac. Later, I'll also cover how Jekyll works and some of its other benefits.

What we'll be using

• Repositories will be hosted on GitHub.

• We'll push to GitHub with GitHub Desktop

• We'll host our blog with Netlify

Creating a Jekyll blog

To create your first Jekyll blog:

1. Create a GitHub account and download GitHub Desktop.

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).

6. Run cd your-blog-name (again, use the name of your blog).

7. Run 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 Command + 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

It's much easier to work with your blog if you can look at it, so let's spin up a local development server. To spin up a local server:

1. Inside the terminal, run jekyll s.

2. Go to localhost:4000 to see your blog as you develop. (It looks pretty bare right now – we'll write some posts soon.)

3. When you want to stop your server, press Ctrl + C. (You might have to hit it twice depending on your setup.)

Editing your blog

To edit your blog, I recommend using a text editor like Visual Studio Code or Sublime Text. To edit your blog:

1. 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
   

2. 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, if you wanted to publish a post on October 10, 2019, you could name it 2019-10-10-jekyll.md.

3. 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 layout and a title on each post.
   • Optionally, you can set a permalink to control the URL for this post. For instance, permalink: jekyll would place the post at yourblog.com/jekyll.
   • You can add formatting to your posts with Markdown.

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

The default Jekyll theme is pretty plain. If you want to customize it, you can download a premade theme or create one of your own by overriding Jekyll's theme defaults.

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.

1. Sign up for a free hosting account at Netlify.

2. 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

3. Your blog is now live on Netlify. The current URL is randomly generated, but you can add a custom domain if you'd like:

   • If you haven't yet bought your domain, I recommend purchasing it from your Netlify dashboard to make things easy on yourself. You can read more about this here.
   • If you've already bought your domain, you can follow Netlify's instructions for hooking it up.

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. (Source on Obama's campaign from one of the engineers who worked on it.)
• 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

Conclusion

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.