Jekyll One

To create content using the Theme JekyllOne for Jekyll, no deep HTML knowledge is required. The sources for all website content pages are based on the well-known top-level markup languages Asciidoc (Asciidoctor) or Markdown. Jekyll processes the Markup source code fully automated and puts out valid standalone HTML5 code.

Managing pages

In addition to writing posts, another thing you may want to do with your Jekyll site is create static pages. By taking advantage of the way Jekyll copies files and directories, this is easy to do.

The Front Matter

The front matter is where Jekyll starts to get really cool. Any file that contains a YAML front matter block will be processed by Jekyll as a special file. The front matter must be the first thing in the file and must take the form of valid YAML set between triple-dashed lines.

Here is a very basic example:

---
layout: post
title: Blogging Like a Hacker
---

Between these triple-dashed lines, you can set predefined variables (see below for a reference) or even create custom ones of your own. These variables will then be available to you to access using Liquid tags both further down in the file and also in any layouts or includes that the page or post in question relies on.

If you use UTF-8 encoding, make sure that no BOM header characters exist in your files or very, very bad things will happen to Jekyll. This is especially relevant if you’re running`Jekyll on Windows`.

If you want to use Liquid tags and variables but don’t need anything in your front matter, just leave it empty! The set of triple-dashed lines with nothing in between will still get Jekyll to process your file. (This is useful for things like CSS and RSS feeds!)

Predefined Global Variables

There are a number of predefined global variables that you can set in the front matter of a page or post.

Variable Description

layout

If set, this specifies the layout file to use. Use the layout file name without the file extension. Layout files must be placed in the _layouts directory.

permalink

If you need your processed blog post URLs to be something other than the site-wide style (default /year/month/day/title.html), then you can set this variable and it will be used as the final URL.

published

Set to false if you don’t want a specific post to show up when the site is generated.

Custom Variables

Any variables in the front matter that are not predefined are mixed into the data that is sent to the Liquid templating engine during the conversion. For instance, if you set a title, you can use that in your layout to set the page title:

<!DOCTYPE HTML>
<html>
  <head>
    <title>{{ page.title }}</title>
  </head>
  <body>
    ...
</html>

Predefined Variables for Posts

These are available out-of-the-box to be used in the front matter for a post.

Variable Description

date

A date here overrides the date from the name of the post. This can be used to ensure correct sorting of posts. A date is specified in the format YYYY-MM-DD HH:MM:SS +/-TTTT; hours, minutes, seconds, and timezone offset are optional.

category

categories

Instead of placing posts inside of folders, you can specify one or more categories that the post belongs to. When the site is generated the post will act as though it had been set with these categories normally. Categories (plural key) can be specified as a YAML list or a comma-separated string.

tags

Similar to categories, one or multiple tags can be added to a post. Also like categories, tags can be specified as a YAML list or a comma-separated string.

Don’t repeat yourself!

If you don’t want to repeat your frequently used front matter variables over and over, just define Front Matter defaults for them and only override them where necessary (or not at all). This works both for predefined and custom variables.

Working with drafts

Drafts are posts without a date. They’re posts you’re still working on and don’t want to publish yet. To get up and running with drafts, create a _drafts folder in your site’s root (as described in the docs structure section) and create your first draft:

|-- _drafts/
|   |-- a-draft-post.md

To preview your site with drafts, simply run jekyll serve or jekyll build with the --drafts switch. Each will be assigned the value modification time of the draft file for its date, and thus you will see currently edited drafts as the latest posts.

Creating pages

In addition to [Managing posts], another thing you may want to do with your Jekyll site is create static pages. By taking advantage of the way Jekyll copies files and directories, this is easy to do.

Homepage

Just about every web server configuration you come across will look for an HTML file called index.html (by convention) in the site’s root folder and display that as the homepage. Unless the web server you’re using is configured to look for some different filename as the default, this file will turn into the homepage of your Jekyll-generated site.

Use layouts on your homepage!

Any HTML file on your site can use layouts and/or includes, even the homepage. Common content, like headers and footers, make excellent candidates for extraction into a layout.

Where additional pages live

Where you put HTML or Markdown files for pages depends on how you want the pages to work. There are two main ways of creating pages:

  • Place named HTML or Markdown files for each page in your site’s root folder.

  • Create a folder in the site’s root for each page, and place an index.html or index.md file in each page folder.

Both methods work fine (and can be used in conjunction with each other), with the only real difference being the resulting URLs.

Named HTML files

The simplest way of adding a page is just to add an HTML file in the root directory with a suitable name for the page you want to create. For a site with a homepage, an about page, and a contact page, here’s what the root directory and associated URLs might look like:

.
|-- _config.yml
|-- _includes/
|-- _layouts/
|-- _posts/
|-- _site/
|-- about.html
|-- index.html
|-- other.md
└── contact.html

Named folders containing index HTML files

There is nothing wrong with the above method. However, some people like to keep their URLs free from things like filename extensions. To achieve clean URLs for pages using Jekyll, you simply need to create a folder for each top-level page you want, and then place an index.html file in each page’s folder. This way the page URL ends up being the folder name, and the web server will serve up the respective index.html file. Here’s an example of what this structure might look like:

.
├── _config.yml
├── _includes/
├── _layouts/
├── _posts/
├── _site/
├── about/
|   └── index.html
├── contact/
|   └── index.html
|── other/
|   └── index.md
└── index.html

This approach may not suit everyone, but for people who like clean URLs it’s simple and it works. In the end, the decision is yours!

Use permalink Front Matter Variable!

Clean URLs can also be achieved using the permalink front matter variable. In the example above, using the first method, you can get URLfor the file other.md by setting this at the top of the file: permalink: /other

Static Files

In addition to renderable and convertible content, we also have static files. A static file is a file that does not contain any YAML front matter. These include images, PDFs, and other un-rendered content.

They’re accessible in Liquid via site.static_files and contain the following metadata:

Variable Description

file.path

The relative path to the file.

file.modified_time

The Time the file was last modified.

file.extname

The extension name for the file, e.g. .jpg for image.jpg

Assets

Jekyll provides built-in support for Sass and can work with CoffeeScript via a Ruby gem. In order to use them, you must first create a file with the proper extension name (one of .sass, .scss, or .coffee) and start the file with two lines of triple dashes, like this:

---
---
// start content
.my-definition
  font-size: 1.2em

Jekyll treats these files the same as a regular page, in that the output file will be placed in the same directory that it came from. For instance, if you have a file named css/styles.scss in your site’s source folder, Jekyll will process it and put it in your site’s destination folder under css/styles.css.

Jekyll processes all Liquid filters and tags in asset files

If you are using Mustache or another JavaScript templating language that conflicts with the Liquid template syntax, you will need to place {% raw %} and {% endraw %} tags around this code.

Sass/SCSS

Jekyll allows you to customize your Sass conversion in certain ways.

Place all your partials in your sass_dir, which defaults to <source>/_sass. Place your main SCSS or Sass files in the place you want them to be in the output file, such as <source>/css. For an example, take a look at this example site using Sass support in Jekyll.

If you are using Sass @import statements, you’ll need to ensure that your sass_dir is set to the base directory that contains your Sass files. You can do that thusly:

sass:
    sass_dir: _sass

The Sass converter will default the sass_dir configuration option to _sass.

sass_dir is only used by Sass.

Note that the sass_dir becomes the load path for Sass imports, nothing more. This means that Jekyll does not know about these files directly, so any files here should not contain the YAML Front Matter as described above nor will they be transformed as described above. This folder should only contain imports.

You may also specify the output style with the style option in your _config.yml file:

sass:
    style: compressed

These are passed to Sass, so any output style options Sass supports are valid here, too.

Coffeescript

To enable Coffeescript in Jekyll 3.0 and up you must

  • Install the jekyll-coffeescript gem

  • Ensure that your _config.yml is up-to-date and includes the following:

gems:
 - jekyll-coffeescript