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.

Requirements

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 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.

A new Jekyll instance

Skip to next section to impot 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 ot 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.
  • _layoutsputs the pieces of the includes together for a post, page and index file.
cd my-site-name
bundle exec jekyll serve

Then, browse to: http://localhost:4000. You can edit files, and Jekyll will make those updates behind the scene as soon as you save...just refresh to see your changes.

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

Jekyll serve command terminal output

Wordpress Import instructions (wordpress.com and self hosted)

Click one of the links below to check out the awesome docs at Jekyll RB.

Drafts

To wok 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 address. Finally, run the below in your temrinal:

bundle exec jekyll serve --drafts
Terminal screen output showing draft folder

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.

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

Terminal screen output showing production folder contents

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.

Resources

Check out these Jekyll tutorials for more on working with the Jekyll static site generator: