Using Slate Engine with Kirby

By James Steel on

3 minutes | Kirby | Tools | Slate

Using Slate Engine with Kirby CMS

Introduction

A short time go we released Slate, our open source sass framework. In this post, we show you how easy it is to configure it to work with the most excellent Kirby CMS.

Kirby is a brilliant flat-file CMS system that is hugely flexible and very fast to build sites with. It's quite easy to extend Slate's build engine to compile assets and live reload content when changes are made inside Kirby's Panel.

This guide assumes you are using a Mac or Linux, but should work fine on other systems. Let's make a start.

Laying the ground

The first thing you are going to need is a copy of Slate Engine. Create a folder for your project on your local development server, and clone Slate Engine into it:

git clone https://github.com/HashandSalt/slateengine.git myproject

The next step is to go ahead and use Yarn (recommended) or NPM to install the default set of dependencies.

yarn install -D

Assuming you have a local domain configured via something like Vagrant, Valet or MAMP, in order to run the project in a browser, you need to tell the engine to use this domain name. Open up webpack.mix.js and scroll down a little way to line 19 and amend it to match your domain name:

proxy: 'http://kirbyslate.salt'

At this stage, if you if you launch the project with yarn start it should compile the default code and spin up an static html page in a browser. So far so good.

Slate Engine First Run

Adding Kirby

For the purposes of demonstration, we are going to use Plainkit which is an official barebones starting point for working with Kirby.

All you need to do is delete the contents of the /public folder, and then copy all the files over for Plainkit to replace them. Remember to show all files, since there is a hidden .htacess file that does need to be copied over too.

If all went well, reloading the page in the browser should present you with the word Home.

Kirby Plain Kit Installed

Magnificent isn't it? That might be true, but it isn't very pretty. We can fix that…

Wiring in CSS and Javascript

Open up /public/site/snippets/header.php. We can use Kirby's CSS & JavaScript helpers. Just before the close head tag, add the following two lines:

<?= css('assets/css/site.css') ?>
<?= js('assets/js/site.js') ?>

Now, if you make changes to the SASS & JS (located in /src/sass/site.scss and /src/js/site.js), you should see the changes reflected in the browser automagically when you save the file. Awesome stuff, however it would be nice if our changes to Kirby's template code and content text files also caused the browser to reload. Read on…

Template and content reloading

Right now our project is building just fine and Kirby is working, however the site is not aware of our compiled CSS and Javascript. It's also still watching for a now non existent index.html. Let's fix this.

Back inside webpack.mix.js, we need to make some changes to the mix.browserSync rule. Remove the line for the html file so you are left with the following:

mix.browserSync({
  proxy: 'http://kirbyslate.salt',
  files: [
    "public/assets/js/**/*.js",
    "public/assets/css/**/*.css"
  ]
})

We need to add in a couple more lines to account for the PHP files and content text files that make Kirby tick:

mix.browserSync({
  proxy: 'http://kirbyslate.salt',
  files: [
    "public/assets/js/**/*.js",
    "public/assets/css/**/*.css",
    "public/site/templates/*.php",
    "public/site/snippets/**/*.php",
    "public/content/**/*.txt"
  ]
})

That's all there is to it. If you launch the project again with yarn start, you will find that changes to the content, template and snippet files will be reloaded in the browser.

TL;DR