Improve this page

Step by Step Tutorial

10. Deployment

In this final step we’ll get the site ready for production.

Gemfile

It’s good practice to have a Gemfile for your site. This ensures the version of Jekyll and other gems remains consistent across different environments.

Create a Gemfile in the root. The file should be called ‘Gemfile’ and should not have any extension. You can create a Gemfile with Bundler and then add the jekyll gem:

bundle init
bundle add jekyll

Your file should look something like:

# frozen_string_literal: true
source "https://rubygems.org"

gem "jekyll"

Bundler installs the gems and creates a Gemfile.lock which locks the current gem versions for a future bundle install. If you ever want to update your gem versions you can run bundle update.

When using a Gemfile, you’ll run commands like jekyll serve with bundle exec prefixed. So the full command is:

bundle exec jekyll serve

This restricts your Ruby environment to only use gems set in your Gemfile.

Note: if publishing your site with GitHub Pages, you can match production version of Jekyll by using the github-pages gem instead of jekyll in your Gemfile. In this scenario you may also want to exclude Gemfile.lock from your repository because GitHub Pages ignores that file.

Plugins

Jekyll plugins allow you to create custom generated content specific to your site. There are many plugins available or you can even write your own.

There are three official plugins which are useful on almost any Jekyll site:

To use these first you need to add them to your Gemfile. If you put them in a jekyll_plugins group they’ll automatically be required into Jekyll:

source 'https://rubygems.org'

gem "jekyll"

group :jekyll_plugins do
  gem "jekyll-sitemap"
  gem "jekyll-feed"
  gem "jekyll-seo-tag"
end

Then add these lines to your _config.yml:

plugins:
  - jekyll-feed
  - jekyll-sitemap
  - jekyll-seo-tag

Now install them by running a bundle update.

jekyll-sitemap doesn’t need any setup, it will create your sitemap on build.

For jekyll-feed and jekyll-seo-tag you need to add tags to _layouts/default.html:

<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <title>{{ page.title }}</title>
    <link rel="stylesheet" href="/assets/css/styles.css">
    {% feed_meta %}
    {% seo %}
  </head>
  <body>
    {% include navigation.html %}
    {{ content }}
  </body>
</html>

Restart your Jekyll server and check these tags are added to the <head>.

Environments

Sometimes you might want to output something in production but not in development. Analytics scripts are the most common example of this.

To do this you can use environments. You can set the environment by using the JEKYLL_ENV environment variable when running a command. For example:

JEKYLL_ENV=production bundle exec jekyll build

By default JEKYLL_ENV is development. The JEKYLL_ENV is available to you in liquid using jekyll.environment. So to only output the analytics script on production you would do the following:

{% if jekyll.environment == "production" %}
  <script src="my-analytics-script.js"></script>
{% endif %}

Deployment

The final step is to get the site onto a production server. The most basic way to do this is to run a production build:

JEKYLL_ENV=production bundle exec jekyll build

And then copy the contents of _site to your server.

Destination folders are cleaned on site builds

The contents of _site are automatically cleaned, by default, when the site is built. Files or folders that are not created by your site's build process will be removed.

Some files could be retained by specifying them within the keep_files configuration directive. Other files could be retained by keeping them in your assets directory.

A better way is to automate this process using a CI or 3rd party.

Wrap up

That brings us to the end of this step-by-step tutorial and the beginning of your Jekyll journey!

Next
  1. Setup
  2. Liquid
  3. Front Matter
  4. Layouts
  5. Includes
  6. Data Files
  7. Assets
  8. Blogging
  9. Collections
  10. Deployment