How you install Hydejack depends on whether you start a new site, or change the theme of an existing site.

  1. New sites
  2. Existing sites
    1. Troubleshooting
  3. GitHub Pages
    1. GH Pages + Free Version
    2. GH Pages + PRO Version
  4. Running locally

New sites

For new sites, the best way to get started with Hydejack is via the Starter Kit. It comes with a documented config file and example content that gets you started quickly.

If you have a GitHub account, fork the Hydejack Starter Kit repository. Otherwise download the Starter Kit and unzip them somewhere on your machine.

If you bought the PRO Version of Hydejack, use the contents of the starter-kit folder instead.

In addition to the docs here, you can follow the quick start guide in the Starter Kit.

You can now jump to running locally.

You can now also Deploy to Netlify directly.

Existing sites

If you have an existing site that you’d like to upgrade to Hydejack you can install the theme via bundler. Add the following to your Gemfile:

# file: `Gemfile`
gem "jekyll-theme-hydejack"

If you bought the PRO Version of Hydejack, copy the #jekyll-theme-hydejack folder into the root folder of your site, and add the following to your Gemfile instead:

# file: `Gemfile`
gem "jekyll-theme-hydejack", path: "./#jekyll-theme-hydejack"

The folder is prefixed with a # to indicate that this folder is different from regular Jekyll content. The # char was choosen specifically because it is on of the four characters ignored by Jekyll by default (., _ , #, ~).

In your config file, change the theme to Hydejack:

# file: `_config.yml`
theme: jekyll-theme-hydejack

Hydejack comes with a default configuration file that takes care most of the configuration, but it pays off to check out the example config file in the Starter Kit to see what’s available.

You can now jump to running locally.


If your existing site combines theme files with your content (as did previous verisons of Hydejack/PRO), make sure to delete the following folders:

  • _layouts
  • _includes
  • _sass
  • assets

The assets folder most likely includes theme files as well as your personal/content files. Make sure to only delete files that belong to the old theme!

GitHub Pages

If you want to build your site on GitHub Pages, check out the gh-pages branch in the Hydejack Starter Kit repo. For PRO users, find the starter-kit-gh-pages folder in the downloaded zip.

Note that Hydejack has a reduced feature set when built on GitHub Pages. Specifically, using KaTeX math formulas doesn’t work when built in this way.

GH Pages + Free Version

For existing sites to use the Free Version, you can instead set the remote_theme key as follows:

# file: `_config.yml`
remote_theme: hydecorp/hydejack@v9.0.5

Make sure the plugins list contains jekyll-include-cache (create if it doesn’t exist):

# file: `_config.yml`
  - jekyll-include-cache

To run this configuration locally, make sure the following is part of your Gemfile:

# file: `Gemfile`
gem "github-pages", group: :jekyll_plugins
gem "jekyll-include-cache", group: :jekyll_plugins

GH Pages + PRO Version

For existing sites to use the PRO Version several steps are necessary, because GitHub Pages does not support keeping theme files in a separate folder.

If it’s possible, use the starter-kit-gh-pages in the downloaded zip. It’s often easier to copy your content into the starter kit than the reverse.

To use Hydejack PRO on GitHub Pages with an existing repository, copy the following files form #jekyll-theme-hydejack into the root of your repo.

  • _layouts
  • _includes
  • _sass
  • assets

You should also copy _data from either of the starter kits.

If possible, use the _config.yml from the starter kit. Otherwise do the following:

Make sure the plugins list contains jekyll-include-cache (create if it doesn’t exist):

# file: `_config.yml`
  - jekyll-include-cache

Make sure neither theme nor remote_theme is present. For local testing make sure math_engine is set to mathjax.

Finally, copy the following (plugin) configurations:

# file: `_config.yml`
# Plugin Configs
# ---------------------------------------------------------------------------------------
  remove_originals:    true

  remove_originals:    true
  with_frontmatter:    true

  collections:         true

  strip_title:         true
  collections:         true

  comments:            ["<!-- ", " -->"]
  clippings:           all
  endings:             all
    envs:              [development]

  style:               compressed

Running locally

Make sure you’ve cded into the directory where _config.yml is located. Before running for the first time, dependencies need to be fetched from RubyGems:

$ bundle install

If you are missing the bundle command, you can install Bundler by running gem install bundler.

Now you can run Jekyll on your local machine:

$ bundle exec jekyll serve

and point your browser to http://localhost:4000 to see Hydejack in action.

Continue with Config