Custom Jekyll Themes Using Clarion
Jekyll is a simple, blog-aware, static site generator. Jekyll also happens to be the engine behind GitHub Pages, which means you can use Jekyll to host your project’s page (like this one), blog, or website from GitHub. Integrating Clarion into Jekyll was very simple.
Starting Your Project
Before you get started, make sure Clarion and the Jekyll requirements are installed:
npm install -g clarion
Jekyll Requirements
This example will use the Jekyll Cayman theme. The following instruction are excerpts from the official documentation:
Create Your Project
Download the theme here.
In the terminal:
unzip jekyll-cayman-theme-master.zip
cd jekyll-cayman-theme-master
bundle install
Adding Clarion
Before Clarion is installed, rename the index.html
file at the core of the project to _index.html
to prevent it from being overridden. Now install Clarion:
clarion new
Remove the new index.html
and rename _index.html
back to index.html
.
In the _includes
directory add a reference to your style and script files to the head.html
file (or in another designated file).
<link rel="stylesheet" href="/build/styles.css" />
<script src="/build/scripts.js"></script>
Note: If you are using your Jekyll project for GitHub Pages, make sure you prefix the href
and src
paths with your project name.
Using the Theme
The Cayman theme uses 2 files in the css
directory: cayman.css
and normalize.css
. You can add the files to your styles in 2 ways:
- Cut and paste them or copy them to the appropriate place and change the extension
- Create new files and and add the contents to the new files
Let's use the CLI to do the latter. Create 2 new files: the first file will go in the src/sass/02_Vendors
directory for the cayman theme and the second will go in the src/sass/01_Base
directory since it is a CSS reset.
clarion add theme cayman
clarion add base normalize
Copy the contents of the css/cayman.css
file to the newly created src/sass/02_Vendors/_cayman.scss
file and css/normalize.css
to src/sass/01_Base/_normalize.scss
.
Now you can remove the references to the to css/cayman.css
and css/normalize.css
in the _includes/head.html
file.
WebPack Watch and Jekyll Serve
When you run jekyll serve
, Jekyll will watch for any changes to you files, process them, and the output will go in the _sites
directory. The problem is that while this process is running you cannot run additional commands or have additional watchers running to compile your styles or scripts. This can be resolved by installing a package called concurrently. This will allow multiple commands to be run simultaneously.
npm i concurrently --save-dev
In the package.json
, under scripts
, update the dev
command to run the webpack watch command and the jekyll serve command simultaneously:
"dev": "concurrently --kill-others \"cross-env NODE_ENV=development webpack -w \" \"bundle exec jekyll serve\"",
Now, update the build
command to include Jekyll's build command:
"build": "cross-env NODE_ENV=production webpack --progress --hide-modules -p && bundle exec jekyll build"
Conclusion
You should be able to use the Clarion CLI as you normally would. No additional configuration is necessary.