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:

1. Cut and paste them or copy them to the appropriate place and change the extension
2. 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.