Initializing your site

This assumes you have a local Ruby environment that’s ready to go. I switched over to rbenv last year from RVM. I highly recommend using rbenv or RVM over system installs of ruby. If you mess up the system installation of Ruby, Python, or any other languages, the blast radius is system wide. If you have a user install of something like rbenv, you can just blow away your user install, reinstall, and you don’t have to worry about system wide issues.

Creating a new Jekyll site

The quick start guide from Jekyll tells you everything you need to know to get started. It’s really as easy as they show:

$ gem install jekyll
$ jekyll new myblog
$ cd myblog
$ jekyll serve

You are now serving your Jekyll site which you can hit at 127.0.0.1:4000/. When you make changes to posts, a refresh is all you need to see your changes in the browser. I generally have both my editor and browser up at the same time when working on a Jekyll site. The site configuration is managed through _config.yml.

Next steps

Version Control

I’d recommend using git for source control. Add all the files and make your first commit:

$ git init
$ git add .gitignore *
$ git commit -m "My first commit"

I use GitHub for hosting repos. If you want to host your own git server, GitLab is a very popular option. I don’t want to run my own git service, so GitHub it is. Once you’ve created your repo through GitHub, add it as a remote, and push up your site:

$ git remote add origin git@github.com:brint/spock.rocks.git
$ git push origin master

I’m not going to publish a tutorial on using git. There are a ton of outstanding ones out there. If you want to try hands on, GitHub has a set of challenges to help you learn git in 15 minutes.

Gemfile

Add a Gemfile since we’re going to add things over time. Here’s what you may want to start with:

source 'https://rubygems.org'

gem 'jekyll'

The Gemfile will help you manage Ruby gem dependencies, and if someone else ever comes into help out, they can run bundle to pick up all required dependencies for development. Optionally, you can add Gemfile.lock to your .gitignore if you want developers to always use the latest versions of gems:

$ echo Gemfile.lock >> .gitignore

Since the Gemfile and Gemfile.lock don’t need to be served when you’re running your site, you can add an exclude section to your _config.yml to ensure they aren’t served. Here’s how you’d add it to a new _config.yml

$ echo 'exclude: ["Gemfile*"]' >> _config.yml

If you already have an exclude section, just add "Gemfile*" to the list of exclusions, which will match any file that starts with Gemfile. The exclude configuration is handy for making sure you only serve what you need to.

Why static sites?

You can host static sites through GitHub Pages or object stores like Amazon S3 and Rackspace Cloud Files. This means that you don’t have to manage any servers. From the perspective of someone who has managed servers for over a decade, this is awesome. Additionally, there is no database to manage or contend with. No schema changes, no sharding, no splittings reads and writes… nada.

Some of the benefits specific to Jekyll include:

  • Blog in Markdown!
  • Sites are programatically generated. If you make changes, just re-generate the site.
  • Things like RSS feeds are generated for you.
  • Jekyll is Ruby under the hood, so you can extend it to add features and functionality. There are a number of plugins already available.
  • Jekyll has a lot of things built in, so you can use 12factor concepts such as storing the configuration in your environment to control your build from local dev to prod.

What about dynamic things like comments?

There are services out there which you can integrate with Javascript such as Disqus. I’ll cover setting this up in Jekyll in a later post.

What about analytics and admin control panels?

With a static site, there aren’t admin control panels. There is a silver lining here, you don’t need to worry about someone compromising an account and doing nasty things to your blog. Additionally, since the site is static, things like XSS and other common attacks won’t work.

You can get analytics through things like Google Analytics. Just like Disqus, this is a little extra Javascript. If you’re using AWS CloudFront to serve your site, there are metrics and insights you can gather from there as well.

What about mobile users?

The default Jekyll css looks fine on phones.

So static sites can do everything?

No, they can’t. Static sites are very handy for things like blogs or things that don’t need to be dynamically generated server side.