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