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.
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
bundle exec jekyll serve
Sample output for running
jekyll new my-site-name.
Jekyll will now generate a site in the folder "
To override the default jekyll theme, you will need ot create two folders as seen in the list below. These are
_layouts. For more information check out overriding theme defaults.
_config.ymlstores the website configuration data such as site name, description and base address. Check out my sample config file.
_postsis where posts for your site are stored in markdown or HTML format. Check out my sample post formatting.
_sitesThis is where the pages will be built into for your production build.
about.mdis the about page for your site.
feed.xmlwill have your rss feed. This generates on its own.
index.mdyour site's main page.
404.htmlyour sites "page not found" file.
gemfilea list of ruby plugins installed
assetswhere you can store your js and other files
sassyour sass code
_includesis 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.
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:
Wordpress Import instructions (wordpress.com and self hosted)
Click one of the links below to check out the awesome docs at Jekyll RB.
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
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
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.
Check out these Jekyll tutorials for more on working with the Jekyll static site generator:
- Configure on Azure or Github Pages
- The configuration file
- Fix pagination after upgrading (V2 to V3)
- Easy searching with JSON and jQuery
- Jekyll on Stack Overflow
- Jekyll Import Docs: Wordpress.com
- Jekyll Import Docs: Wordpress (self install)
- Jekyll Docs - Working with drafts
- Jekyll Docs - Installation Problems