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.
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.
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,
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: email@example.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.