Jekyll and GitHub Pages is a combination that’s hard to beat. Free and lightweight, you can use this combination to host a static website or blog. Unlike most other solutions, you simply generate your content and host it statically. This means not only a fast site, but one that is immune from many security issues that other blog software encounters. The problem, of course, is that Jekyll is a bit technical to use and to get set up. Once it’s set up, though, it’s quite easy to create content.
The majority of the instructions below are one-time setup items. When you’re simply wanting to update content or add a new blog post, you only need to follow the directions under the Adding New Content section. More detailed instructions on using Jekyll can be found in the excellent documentation on the Jekyll home page.
I’ll be using a Mac for this, though the instructions are very similar for a Linux machine. To get started, you’ll need:
- A domain name - Having your own domain name keeps your content indepedent of the underlying blogging platform.
- A free GitHub account
- Plain Text editor of choice (TextMate, Sublime Text, TextWrangler, BBEdit, etc.)
- Understanding of Markdown syntax - GitHub has a nice Markdown Basics page
Once you have set up your GitHub account, create a new repository. (If you want to keep your content private, you can pay an inexpensive monthly fee.) You can name the repository anything you like, though I suggest naming it after your domain name. This is a one-time action.
Check the box to initialize the repository with a README file, choose Jekyll from the .gitignore dropdown, and add a license if desired.
Set default branch
After your repository has been created, you will want to create a new branch and set it as the default.
On the left-hand side of the screen, click the dropdown that says Branch: master, type in
gh-pages, and click Create branch: gh-pages to create the branch.
Now, set your newly created
gh-pages branch as the default branch. Click Settings, Branches, and choose
gh-pages from the dropdown under the Default branch heading. Click Update and click through the Are you sure? notification.
Installing GitHub Desktop
Download GitHub Desktop and install it on your Mac. We will use this to keep a local copy of your site on your computer and synchronize changes back to GitHub with it. After installation, open GitHub Desktop, log into your GitHub account, and add the repository you created previously.
Choose File, Clone Repository, select your repository, and click the Clone button. Choose a location to store the clone. (I normally choose the Sites folder on my Mac.) This will create a subdirectory named after your repository in the folder you chose.
There are several ways that you can install Jekyll locally. The following approach will ensure that you’re consistent with the version of Jekyll and the plugins GitHub Pages uses.
Step 1: Homebrew (for Mac only)
If you’re on a Mac, the first thing to do is to install Homebrew. Follow the instructions on the homepage. You may additionally be prompted to install OS X Command-Line Tools first.
Step 2: Ruby and GitHub Pages gems
To install Jekyll, run the following commands from the Terminal:
brew install ruby
gem install github-pages
This installs an updated version of Ruby into
/usr/local/bin, as well as Jekyll and all plugins used by GitHub for GitHub Pages. More details can be found under the Installing Jekyll heading on the Using Jekyll with GitHub Pages page.
(Note: This page also mentions how to keep Jekyll updated.)
You may choose to follow the instructions to create an empty Jekyll site on the aforementioned instructions. However, many people opt to start with a theme, which has the basic structure of a Jekyll site. There are many places to find a Jekyll theme. Some examples include:
We will use the main Poole theme. Simply choose the Download button on the right-hand side of the page. Extract the contents and place them in your local copy of your repository. Changes you need to make vary per theme, as there is no actual standard on theme creation or configuration.
_config.yml configuration file and change a few settings. For example, let’s change the follow sections:
# Setup title: My Example Blog tagline: Just another hello world. url: http://www.example.com paginate: 1 baseurl: "" # About/contact author: name: Your Namehere url: https://twitter.com/example email: email@example.com
Additional changes may need to be made to the theme pages, which are in the
_layouts folders. Additional files like
index.html may need modifications too.
Previewing Content Locally
Now that the basic setup is complete, run Jekyll locally to test the site configuration and see how the site looks. Being able to preview posts locally prior to generation is useful, and something you can do when working on drafts. To run Jekyll, open up a Terminal window, navigate to the main directory for you site by typing something similar to
cd Sites/www.example.com, and type
jekyll serve. You’ll see something similar to the content below:
Configuration file: /Users/trhall/Sites/www.example.com/_config.yml Source: /Users/trhall/Sites/www.example.com Destination: /Users/trhall/Sites/www.example.com/_site Generating... done. Auto-regeneration: enabled for '/Users/trhall/Sites/www.example.com' Configuration file: /Users/trhall/Sites/www.example.com/_config.yml Server address: http://0.0.0.0:4000/ Server running... press ctrl-c to stop.
Now, go to your browser and navigate to http://localhost:4000/ and you’ll see the homepage for the site if all went well.
If you want to make additional changes to posts or the homepage, simply make changes and save them. The changes will apply automatically when you refresh the site in your browser. Note: If you want to make changes to your configuration file, you’ll have to stop and restart Jekyll for those changes to take effect. Simply go back to the Terminal window and type
Ctrl-C to stop Jekyll and type
jekyll serve again.
You may want to remove the sample pages in the
_posts directory and add your own first entry. Files are named using a
YYYY-MM-DD-your-title-here.md convention. Drafts can be created by using
YYYY-MM-DD on the front.
Configuring Your Domain Name
In order to allow GitHub Pages to serve up your site from your own domain name, you need to create a
CNAME file (all caps) to GitHub Pages to use your domain name instead of their default github.io name. In the top level of your repository directory, create a file named
CNAME (all caps, no file extension) with the name of your site as the contents of the file. For example:
You also must configure a CNAME entry with your domain registrar. Have it point
youruserid.github.io, where youruserid is the user ID registered with GitHub.
Deploying the Site
Now that you are sure that the site is set up to your liking, you are ready to deploy the site. Since you’re done testing locally, stop Jekyll in the Terminal by typing
Ctrl-C. Then, go to GitHub Desktop under the Uncommitted Changes tab, type in a summary (and optional description) and click the Commit and Sync gh-pages button. If everything went well, you should see your blog online via the CNAME domain entry you created.
Adding New Content
To add new content, simply create a new post. Preview locally by running
jekyll serve. When you’re ready to publish a post, use GitHub Desktop to Commit and Sync and view your new content!
Quick Fixes via GitHub
If you’re not near a computer that you have Jekyll installed on and simply need to make a quick change to a page or if you want to type a post directly into a web browser editor, you can do the basics using the GitHub website interface. This interface is limited to adding or editing text content, so you can’t easily upload images. But it works in a pinch.
Simply navgiate to the repository on GitHub, navigate to the
_posts directory, then either:
- Edit Existing: Choose an existing file and click the Edit (pencil) icon
- Create New: Click the New File button
Alternative Ways to Add Content
While editing directly in GitHub works, it isn’t ideal. However, Prose.io to the rescue! Prose.io was created by Development Seed to more easily edit Jekyll sites on GitHub Pages. Fun Fact: Prose was used to create and maintain the HealthCare.gov website.
You can authorize Prose to access your GitHub account and then you can edit posts or create new files (including uploading images) via a web-based editor. It even has the ability to preview content and can work with drafts or publish a page for you. Did I mention it’s free?
iOS: Working Copy
Sometimes you need to edit content on the go. With Working Copy, you can directly view and edit content from GitHub. Content can be edited directly in the application or sent to some well-known editors on iOS, including Editorial and Byword. Once you sync back to GitHub, your changes will automatically be picked up.
Posted on 2015-12-18 #blog #howto #github #jekyll