Jekyll: Setting up your development environment

Jekyll is a static site generator that runs on NodeJS. Its a great alternative to WordPress that eliminates the need for databases.

This post was originally written on March 17, 2015. It has been updated for Mac OS Catalina forward.

Requirements

To use Jekyll, you will need to have Ruby installed. Check out the blog post Install homebrew on Big Sur if your on a Mac. Otherwise, check out Ruby Installer for Windows

Install Jekyll dependencies:

To install Jekyll, run the command:

gem install jekyll bundler

You can import your current WordPress posts, by first exporting your entire Wordpress blog using the WordPress tool to Export to an XML file.

Once your export file is ready, you will need to install the Jekyll Importer by the below command:

gem install jekyll-import

Here is a list of other plugins that may be useful in your blog:

There is a list over on the jekyll website (separated by category).

A new Jekyll instance

Skip to next section to import your WordPress blog.

First, run the the below command, replacing "my-site-name" with the folder name for your site.

jekyll new my-site-name
cd my-new-site-name
bundle exec jekyll serve

Sample output for running jekyll new my-site-name.

Jekyll will now generate a site in the folder "my-site-name".

To override the default jekyll theme, you will need to create two folders as seen in the list below. These are assets, sass, _includes and _layouts. For more information check out overriding theme defaults.

_config.yml: stores the website configuration data such as site name, description and base address. Check out my sample config file.
_posts: is where posts for your site are stored in markdown or HTML format. Check out my sample post formatting.
_sites: This is where the pages will be built into for your production build.
about.md: is the about page for your site.
feed.xml: will have your rss feed. This generates on its own.
index.md: your site's main page.
404.html: your sites "page not found" file.
gemfile: a list of ruby plugins installed
assets: where you can store your js and other files
sass: your sass code
_includes: is where you store portions of a file such as your menu, header, footer, and analytics code.
_layouts: puts the pieces of the includes together for a post, page and index file.

cd my-site-name
bundle exec jekyll serve

Below is what the directory will look like in the terminal, as well as the output running the servecommand to preview your site locally:

WordPress Import instructions

Click one of the links below to check out the awesome docs at Jekyll RB. Choose whether you have both wordpress.com or self hosted.

Drafts

To work on a post locally (but not moving it live), create a folder at the root called _drafts. Next, add a markdown or html file without the date (for example: template.html instead of 2019-12-11-template.html).

Finally, run the below in your terminal:

bundle exec jekyll serve --drafts

Changes can be made on the fly using this method as well. When ready to publish, move the file to _posts and add a date.

Ruby 3.0+ Issues

As per the Jekllrb Github Issue you may need to run the command:

bundle add webrick

Publishing your new site

The last step is in this process is to push your files on-line. First, instead of jekyll serve you will want to run jekyll build like below. This replaces all of your development links with what your production link. Check out how to set your configuration.

bundle exec jekyll build

Move into the root of _site. These are the production ready files that should be moved to your server.

The first chunk of files below shows the root of my Jekyll site, while the second shows the production ready files. Note that some files from the root of the Jekyll site are not included. These are excluded in _config.yml

Note that if you use GitHub pages, you will need to compile the files on your computer first then commit your files to the master branch.