So you want to start a blog. Maybe spread your newfound programming knowledge. Or maybe you’re posting a writeup about one of your projects. Or writing a cool baking recipe. But you don’t want to manage your own CMS like WordPress, or hosting, or DNS, or all that manual labour work. You want something that just works. You stumble upon Medium. Medium is great. Huge fan. But you want more. You don’t want to fit into the cookie cutter mold. You want your own site. Your own style. A little flair. The answer?
Jekyll + Github Pages
Or as I like to call it: Jekhub Pages. The name needs a little work.
So what’s Jekyll?
Jekyll is a blogging framework written in Ruby. It’s super simple and easy to set up. You can have it up and running in 10 minutes. And then spend hours customizing everything to your hearts content. Jekyll allows you to write your blog posts in markdown and will automatically convert it to a web page. Jekyll also comes with some sweet themes which you can customize or build yourself.
How does Github come into play?
Great question. Github is the magical glue that binds this together. Github offers a wonderful service called Github Pages. Github Pages offers a free webpage linked to your Github account based on a Github repo. Hosting is free and everything is updated with a simple git push.
Sounds cool. How do I start?
Before you start: If you are not vaguely familiar with Github or the command line, I would recommend learning about those first
1. Signup for Github
2. Create a Github repo
Create a Github repo named [yourusername].github.io
In my case this would be noahbres.github.io. This will also be the URL for your new website so choose wisely.
3. Install Jekyll
So there’s a few steps to this. But once you get this out of the way then everything will be smooth sailing.
I will be providing a super summarized version of the install instructions. Please visit the jekyll install instrucitons for proper instructions
- Download Ruby
- If on Windows: follow this link
- If on MacOS: MacOS should have Ruby pre-installed
- If on Linux: You probably already know what to do just visit the jekyll install page for the package name
- Open the command prompt and run
gem install jekyll bundler- This will install Jekyll and Bundler
- Check if Jekyll was installed properly. Run
jekyll -vin the command prompt - Install git
- If on Windows: follow this link
- If on MacOS: follow this link or install via Homebrew
- If on Linux: Use your favorite package manager and install
4. New Jekyll Project
Run jekyll new username.github.io in your preferred directory and move into that directory (dir for windows, cd otherwise)
jekyll new username.github.io
username.github.io created
dir username.github.io
You will be in a folder containing the foundation for your blog. It should contain the following files: .gitignore, 404.html, about.md, Gemfile, index.md, _config.yml, a _posts and _site folder. (The _site folder may not appear until you run bundle exec jekyll serve)
The 404.html is the page that the user is redirected to when a page isn’t found. The .gitignore file lists files and directories that Git should ignore. Gemfile is used by Ruby to manage your libraries. index.md is the main page. about.md is an about page. _config.yml is used to configure your blog. The default theme is minima provided by Jekyll.
5. Configure Jekyll
Open the config.yml in a chosen text editor (I highly recommend Sublime Text). You will see something like this:
1
2
3
4
5
6
7
8
9
10
11
12
13
title: Noah Bresler
email: noahbres@gmail.com
description: Noah Bresler. Frontend developer, designer, student.
baseurl: "" # the subpath of your site, e.g. /blog
url: "" # the base hostname & protocol for your site, e.g. http://example.com
twitter_username: noahbres
github_username: noahbres
# Build settings
markdown: kramdown
theme: minima
plugins:
- jekyll-feed
Customize the data to fit your own blog. Fill in your own name, email, etc etc. You get it. Ignore the build settings for now.
6. Run Jekyll
With your basic configuration done, run bundle exec jekyll serve and you should see something like this:
bundle exec jekyll serve
Configuration file: C:/Users/Pedro/Desktop/username.github.io/_config.yml
Source: C:/Users/Pedro/Desktop/username.github.io
Destination: C:/Users/Pedro/Desktop/username.github.io/_site
Incremental Build: disabled. Enable with --incremental
Generating...
Done in 4.3 seconds.
Auto-regeneration: enabled for 'C:/Users/Pedro/Desktop/username.github.io'
Server address: http://127.0.0.1:4000/
Server running... press ctrl-c to stop.
Your Jekyll server is now running and serving your blog at 127.0.0.1:4000 which is the localhost server. Type 127.0.0.1:4000 in a browser and visit to see your blog. It should look something like this.
7. Writing your first post
In the directory containg your blog, navigate to the _posts folder. If it doesn’t exist just create one. All your posts live here. The files use the pattern YYY-MM-DD-name-of-post.md for their naming scheme. Y is year, M is month, D is day. (ISO 8601 woop woop).
Here’s a typical post:
1
2
3
4
5
6
7
8
--------
layout: post
title: " \"Welcome to Jekyll!\""
date: 2015-11-17 16:16:01 -0600
categories: jekyll update
--------
You’ll find this post in your `_posts` directory. Go ahead and edit it and re-build the site to see your changes. You can rebuild the site in many different ways, but the most common way is to run `bundle exec jekyll serve`, which launches a web server and auto-regenerates your site when a file is updated.
The text between the dotted lines is the information about the blog post. You specify the layout, the title, the date, the categories, etc, within this top area.
8. Host on Github Pages
Finally you have your first post up and running. You want to share it with the world. What do you do?
Remember that Github repository we created earlier? You’ll be pushing all your code to that.
Close the bundle exec jekyll serve command if it’s still running by typing ctrl + c. Initialize the directory as a local Git repo by running git init. Then stage the content by running git add . (Make sure the period is there). Commit everything with git commit -m "Launching blog! 🚀". Customize the message as you wish. Finally, connect your local repo to the remote repo. Use the command git remote add origin https://github.com/username/repo-name.git. Replace repo-name with the name of the repository (in this case username.github.io). Push the local repo content to the remote repo by running the command git push -u origin master.
git init
Initialized empty Git repository in C:/Users/Noah/Desktop/noahbres.github.io
git add .
git commit -m "Launching blog! 🚀"
[master (root-comit) 6612d7d] "Launching blog! 🚀"
1 file changed, 0 insertions(+), 0 deletions(-)
create mode 100644 index.md
git remote add origin https://github.com/NoahBres/noahbres.github.io
git push -u origin master
Username for 'https://github.com': noahbres
Password for 'https://noahbres@github.com':
Counting objects: 3, done.
Writing objects: 100% (3/3), 22d bytes | 223.00 KiB/s, done.
Total 3 (delta 0), reused 0 (delta 0)
To https://github.com/NoahBres/noahbres.github.io
* [new branch] master -> master
Branch 'master' set up to track remote branch 'master' from 'origin'
Congrats you’re done! Github will now publish your page at the url https://username.github.io. It may take a few minutes for Github to get up and running though.
Want to get deeper into customizing Jekyll? Check out the docs. Enjoy your new blog!
Need any help? Happy to help on Twitter @NoahBres