Jekyll for Web Designers

One of my favorite things about Jekyll is how it gets out of the way and lets you, the designer, actually design. Jekyll imposes no type of structure or framework, no default classes, layout, or coding conventions. You’re free to structure and style your content as you see fit. As such how you plan and author your styles is entirely up to you. There are, however, a few things you want to keep in mind when writing CSS for a Jekyll site.

Location

Normally I like to keep styles in a directory titled _css. This naming convention doesn’t work for Jekyll, as an underscore at the beginning of a directory signals Jekyll to process the contents of the directory and not to include it in the final directory structure. As such to ensure your CSS is copied to the finished site be sure to name it css or a similar name that doesn’t start with an underscore.

Linking

There are essentially two ways to link to external resources like CSS within Jekyll pages and templates. One would be to use the site baseURL to prefix your CSS files:

<link rel="stylesheet" href="{{ site.baseurl }}/css/main.css">

If your site will always be served from the root folder, you can eliminate the site.url object and just use a site-root relative link:

<link rel="stylesheet" href="/css/main.css">

It’s important to note here that relative links for assets like CSS can be difficult when hosting sites on Github Pages. Essentially there are two ways to host pages on Github Pages, as either user/organization pages or project pages.

User and organization pages live in a GitHub repository dedicated to only the GitHub Pages files and are stored in the master branch. This repository must be named after the account name, which will be username.github.io.

Project Pages are stored in the same repository as the project they are for, except that the website content is stored in a specially named gh-pages branch. The master branch can hold the project itself, or even be empty.

This matters because if the site is served through a project page, its baseURL changes as the site is served through a subpath of your user domain at username.github.io/project. This means that in these cases, you’ll need to set your baseURL to /project-name. Note the leading slash and no trailing slash. This can also lead to problems when testing the files locally, so be sure to read Jekyll’s documentation on hosting with Github Pages for a full account.

Jekyll and SASS

Jekyll comes with built-in support for SASS, so there’s no need to install or modify your configuration in order to make it work. There are, however, one or two things you need to keep in mind as you work with SASS in Jekyll.

First, in order to ensure Jekyll processes SASS files, you need to put an empty front matter string at the top of the page. You can include a comment if you’d like, but it doesn’t really matter. So include this at the top of each SASS file:

---
# Front matter added to ensure Jekyll processes file.
---

// write styles after front matter

If you look at Jekyll’s default directory structure, you no doubt saw the _sass directory, which can lead to some confusion about where to place SASS files. Jekyll copies over any processed SASS file in the exact same location it was processed. So, if you have the file css/styles.scss it will be processed and placed at css/styles.css in the generated site. The _sass directory is for SASS import files. If you place the partial .scss files that you are importing and use @import to assemble them into your main stylesheet, Jekyll will process and assemble them at runtime.

So if you do something like this in your main .scss file:

---
# Front matter added to ensure Jekyll processes file.
---

// Imports
@import "type";
@import "layout";
@import "components";

//styles

Place the files type.scss, layout.scss, and components.scss in the _sass directory and Jekyll will do the rest!