Creating a site with Jekyll is easy, once you’ve done the hard work of selecting it from the bevy of other options. The main prerequisites are Ruby (a.k.a. the best programming language in the world) and Rubygems, its package manager.
The Jekyll instructions say:
at the terminal prompt, simply run the following command to install Jekyll
gem install jekyll
Unfortunately, with a plain vanilla installation of OSX Yosemite, you are likely to see the following error:
ERROR: While executing gem … (Gem::FilePermissionError)
You don’t have write permissions for the /Library/Ruby/Gems/2.0.0 directory
This makes sense, actually, because the whole
/Library directory is owned by the root superuser, and contains various system-wide software libraries.
A quick fix would be to throw a
sudo in front of the command, allowing you to execute the command as a superuser. I think a better solution is to install rbenv first, as described in my post about setting up my development environment. This is a bit more work, but the payoff is that in the future, you will be able to easily install and manage gems as your regular user (obviating the need for sudo). There is a good discussion about gem installation on Stack Overflow, for further reading.
So, go install rbenv, then come back and run:
gem install jekyll
New site structure
At this point, assuming you have installed the Jekyll gem (one way or another), create a new directory for your site. In this example, we’ll put everything under blog with all the Jekyll-specific files in a subdirectory www.
mkdir -p blog/www && cd blog/www
Within this directory, run:
jekyll new .
You should see a message like New jekyll site installed, and find various files and directories that Jekyll just generated:
. ├── _config.yml ├── _includes │ ├── footer.html │ ├── head.html │ └── header.html ├── _layouts │ ├── default.html │ ├── page.html │ └── post.html ├── _posts │ └── 2015-04-23-welcome-to-jekyll.markdown ├── _sass │ ├── _base.scss │ ├── _layout.scss │ └── _syntax-highlighting.scss ├── about.md ├── css │ └── main.scss ├── feed.xml └── index.html
The most important directory is _posts, which stores your content (currently consisting of one auto-generated post). For more details, consult the documentation covering the directory structure.
Running Jekyll locally
At this point, you already have a working site! To see it, run:
Then use your browser to point to http://127.0.0.1:4000/, and you should see something like:
The initial auto-generated post looks like:
Posting something new
Creating a new post is as easy as creating a new file in the _posts subdirectory. Start by copying the example post:
cp _posts/*welcome-to-jekyll.markdown _posts/`date +%F`-my-new-post.markdown
This uses the
date shell command to create a
YYYY-MM-DD formatted datestamp. In my case, this created a new file called
2015-04-23-my-new-post.markdown. Edit this file, especially the top part, so that the title is different:
--- layout: post title: "My new post!" date: 2015-04-23 17:45:06 categories: jekyll update ---
After saving, go back to http://127.0.0.1:4000/, and you should see both posts listed:
You can deploy a Jekyll site practically anywhere, because it’s static. To build your site for deployment, run:
All of the distributable (deployment) files end up in the _site subdirectory, which you can upload to a host of your choice. The documentation lists some reasonable methods for deployment. Another cool method is hosting via GitHub Pages which is especially nice if you’re already on GitHub.