Install
How you install Hydejack depends on whether you start a new site, or change the theme of an existing site.
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 the contents somewhere on your machine.
If you bought the PRO Version of Hydejack, use the contents of the starter-kit folder instead.
You can now jump to running locally.
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"
Next, in your config file, change the theme to Hydejack:
# file: `_config.yml`
theme: jekyll-theme-hydejack
You can now jump to running locally.
PRO Customers
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 # character was chosen because it is on of the four characters ignored by Jekyll by default (., _ , #, ~)
Alternatively, if you’ve been added to the “PRO Customers” team on GitHub, you can add Hydejack PRO as a git dependency instead:
# file: `Gemfile`
gem "jekyll-theme-hydejack", git: "https://github.com/hydecorp/hydejack-pro", tag: "pro/v9.2.1"
If you’ve provided your GitHub username during checkout you should have been automatically added to the team. Otherwise you can request an invite via [email protected].
In order for Bundle to fetch the private repository, an environment variable named BUNDLE_GITHUB__COM must be set to x-access-token:<GH_REPO_PAT>, where you replace <GH_REPO_PAT> with a GitHub Personal Access Token (PAT) that has the “repo” permission.
After you’ve secured a way to fetch the jekyll-theme-hydejack gem, 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 annotated example config file from the Starter Kit to see what’s available. See chapter Config for more.
You can now jump to running locally.
Troubleshooting
If your existing site combines theme files with your content (as did previous versions of Hydejack/PRO), make sure to delete the following folders:
_layouts_includes_sassassets
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
As of September 2024, the recommended way of deploying to GitHub Pages is through a custom GitHub Action, which gives you full control over the build process. No extra steps are required when using a GH Action and you can jump to running locally, or learn more in chapter Deploy. That being said, Hydejack maintains backwards compatibility with the legacy pipeline and you can continue to use it.
If you want to build your site using the legacy pipeline, you can build off of the gh-pages branch in the Hydejack Starter Kit repo.
The main difference to the regular starter kit is the use of remote_theme setting in the config file.
# file: `_config.yml`
remote_theme: hydecorp/[email protected]
This setting only works with the Free Version of Hydejack. PRO Customers should use the starter-kit-gh-pages folder in the downloaded zip file when targeting the GitHub Pages legacy pipeline.
starter-kit-gh-pages is only required when deploying to GitHub Pages through the legacy build pipeline. When using a custom GitHub Action, the regular starter-kit provides a cleaner, less cluttered folder structure.
Make sure the plugins list contains jekyll-include-cache (create if it doesn’t exist):
# file: `_config.yml`
plugins:
- 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
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.
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
