layout: page description: Manage and Write Content with Jekyll
title: Manage Pages tagline: Manage and Write Content with Jekyll
group: pages toc: true
:website: jekyllrb.com/docs/posts/ :revnumber: 3.2.1
//Ref :liquid-date-formats: docs.shopify.com/themes/liquid-documentation/filters/additional-filters#date
- .boxShadow
-
¶ ↑
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 wayJekyll
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 byJekyll
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:
- source, yaml
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.
- WARNING
-
¶ ↑
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`.¶ ↑
- NOTE
-
¶ ↑
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.
- width=“100%”, cols=“4,8”,options=“header”, role=“table-responsive mt-3”
-
|======================================================================= |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:
- source, html
<!DOCTYPE HTML> <html>
<head> <title>{% raw %}{{ page.title }}{% endraw %}</title> </head> <body> ...
Predefined Variables for Posts¶ ↑
These are available out-of-the-box to be used in the front matter for a post.
- width=“100%”, cols=“4,8”,options=“header”, role=“table-responsive mt-3”
-
|======================================================================= |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.
a| `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 en.wikipedia.org/wiki/YAML#Lists[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. |=======================================================================
- NOTE
-
¶ ↑
*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:
- source, text
|– _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 [writing posts](../posts/), another thing you may want to do with your
Jekyll
site is create static pages. By taking advantage of the wayJekyll
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.
- NOTE
-
¶ ↑
*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:
- source, text
. |– _config.yml |– _includes/ |– _layouts/ |– _posts/ |– _site/ |– about.html # => example.com/about.html |– index.html # => example.com/ |– other.md # => example.com/other.html └── contact.html # => example.com/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:- source, text
. ├── _config.yml ├── _includes/ ├── _layouts/ ├── _posts/ ├── _site/ ├── about/ | └── index.html # => example.com/about/ ├── contact/ | └── index.html # => example.com/contact/ |── other/ | └── index.md # => example.com/other/ └── index.html # => example.com/
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!
- NOTE
-
¶ ↑
*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 URL `example.com/other` for 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:
- width=“100%”, cols=“4,8”,options=“header”, role=“table-responsive mt-3”
-
|======================================================================= |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:- source, sass
// 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`.- NOTE
-
¶ ↑
Jekyll
processes all Liquid filters and tags in asset filesIf 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:
- source, yaml
sass:
sass_dir: _sass
The Sass converter will default the `sass_dir` configuration option to `_sass`.
[example-sass]: github.com/jekyll/jekyll-sass-converter/tree/master/example
- NOTE
-
¶ ↑
*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:
- source, yaml
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:
- source, yaml
gems:
- jekyll-coffeescript
-
-