Objectives

This is Part 2 of a series called Hello, World: Blog.

Once you have a server capable of hosting content, the next step is creating that content. We’ll use Jekyll, a static site generator designed for blog-style websites, to do so.

In this post, you’ll:

  • Generate site content using Jekyll.
  • Run the site locally to develop and draft posts.

Install Dependencies

Note: Make sure you’re working on your local environment. If you’re still logged into the Ubuntu server from the previous post, use exit to close the connection. See the previous post for more information about environments.

In order to use Jekyll, we’ll need to install two Ruby packages (also known as gems): Jekyll and Bundler.

If you aren’t sure whether Ruby and the gems are already installed, you can check on the command line. Each package has a command with a -v (version) flag. If the command displays a version without any errors, it’s installed.

$ ruby -v
ruby 2.5.1p57 (2018-03-29 revision 63029) [x86_64-darwin17]
$ jekyll -v
jekyll 3.8.2
$ bundle -v
Bundler version 1.16.2

If Ruby is not available, follow the docs to install it on your operating system.

Once Ruby has been installed, use the gem command to install Jekyll and Bundler.

$ gem install jekyll bundler

Generate and Preview the Site Code

Now we’re ready to create a Jekyll project. cd to the directory you want to contain your project folder, and use jekyll new. This command accepts a folder name as an argument. Feel free to replace “blog” below with a different folder name.

$ jekyll new blog

This command creates a “blog” folder in the current directory, and populates it with some Jekyll boilerplate files.

├── 404.html
├── Gemfile
├── Gemfile.lock
├── _config.yml
├── _posts
│   └── 2018-07-01-welcome-to-jekyll.markdown
├── about.md
└── index.md

Websites use HTML (HyperText Markup Language) to render content. However, many of the files we’ve generated have the .md, or Markdown, extension. In order to put this content on a website, we have to build the Markdown into HTML pages that the browser can understand.

This build step, from Markdown to HTML, will allow us to write blog posts in plain text without worrying about the underlying code of the site. We’ll use Jekyll to build the site.

$ jekyll build

This creates a directory called _site in your project folder, containing HTML and CSS. From this point on, we’ll refer to the “blog” directory as our site code, and the “_sites” directory as our site content.

Before putting the content on our site, we should preview it locally. cd into your project directory and use Jekyll’s serve command to host the site locally:

$ cd blog
$ jekyll serve

You’ll see some output that looks like this.

            Source: /Users/brittany/code/projects/blog
       Destination: /Users/brittany/code/projects/blog/_site
 Incremental build: disabled. Enable with --incremental
      Generating... 
                    done in 0.42 seconds.
 Auto-regeneration: enabled for '/Users/brittany/code/projects/blog'
    Server address: http://127.0.0.1:4000/
  Server running... press ctrl-c to stop.

While the serve command is running, you can open http://127.0.0.1:4000 in your browser to preview your blog. It also watches your Markdown for changes, and automatically rebuilds.

To test this, make a small change to the placeholder post provided by Jekyll, _posts/2018-07-01-welcome-to-jekyll.markdown, while jekyll serve is running. You should see a message in the terminal indicating that a file has changed.

Regenerating: 1 file(s) changed at 2018-07-01 23:20:25 ...done in 0.188057 seconds.

Refresh the site in the browser to see your changes. This automatic reload makes it easy to draft or edit posts and see what they’ll look like in the browser.

Customizing the Jekyll Site

Jekyll uses site templates to manage the look and feel of your website. The templates are used to generate the HTML and CSS of your final site. By default, Jekyll uses the minima template.

Although templates are convenient, there are a few things on the boilerplate site that we should change. In your Jekyll directory, open the _config.yml file. This will be pre-populated with some default values, which you can customize.

Here is an example of what my site’s configuration looks like:

title: bannmoore
email: moore.brittanyann@gmail.com
description: >- # this means to ignore newlines until "baseurl:"
baseurl: "" # the subpath of your site, e.g. /blog
url: "http://brittanymoore.net" # the base hostname & protocol for your site, e.g. http://example.com
twitter_username: bannmoore
github_username:  bannmoore

# Build settings
markdown: kramdown
theme: minima
plugins:
  - jekyll-feed

To learn more about configuring a Jekyll site, check out the documentation.

In the next post, we’ll set up a deployment process and move our site code to the server.