Understanding Jekyll Posts

Overview

Posts can be nested in subdirectories but they always must be inside a _posts folder.

Their filename should follow the following format: YYYY-MM-DD-article-name.MARKUP.

In this case article-name will be used as the post slug and if there is no title in the front matter of the post, it will be converted to a title version removing the - chars.

Post metadata

This is a common term used in Book design, to refer to the first section of a book, usually its smallest section.

In a Jekyll context, each post can have page-specific variables to be included at the beginning of the file using YAML format. This metadata is called in Jekyll Front Matter, and is the common place to define things like the post title, layout, description, or override site-wide variable values.

A common post looks like the following code, where the front matter goes inside --- tag, and then the content of the post:

---
layout: post
title: My cool blog
---

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Ut enim ad minim veniam, quis nostrud exercitation ullamco 
laboris nisi ut aliquip ex ea commodo consequat.

Variables

.
├── one_category
│   └── second_category
│      └── _posts
│	     └── nested_post.md
└── _posts
   ├── a_post.md
   └── another_post.md

Variables of a Post and Documents Posts

Front matter

Predefined Variables that can be used in the front matter for a post:

page.title

The title of the Page.

page.date

The Date assigned to the Post. This can be overridden in a Post’s front matter by specifying a new date/time in the format YYYY-MM-DD HH:MM:SS (assuming UTC), or YYYY-MM-DD HH:MM:SS +/-TTTT (to specify a time zone using an offset from UTC. e.g. 2008-12-14 10:30:00 +0900).

page.categories

The list of categories to which this post belongs. Categories are derived from the directory structure above the _posts directory. For example, a post at /work/code/_posts/2008-12-24-closures.md would have this field set to ['work', 'code']. These can also be specified in the YAML Front Matter.

page.tags

The list of tags to which this post belongs. These can be specified in the YAML Front Matter.

In templates

Variables also available in templates

page.content

The content of the Page, rendered or un-rendered depending upon what Liquid is being processed and what page is.

page.excerpt

The un-rendered excerpt of the Page.

page.url

The URL of the Post without the domain, but with a leading slash, e.g. /2008/12/14/my-post.html

page.id

An identifier unique to the Post (useful in RSS feeds). e.g. /2008/12/14/my-post

page.path

The path to the raw post or page. Example usage: Linking back to the page or post’s source on GitHub. This can be overridden in the YAML Front Matter.

page.next

The next post relative to the position of the current post in site.posts. Returns nil for the last entry.

page.previous

The previous post relative to the position of the current post in site.posts. Returns nil for the first entry.