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

graph LR Collections["Collections"] == 1 === ColRelationship{" "} ColRelationship == N === Collection Collection["Collection

label
docs
files
relative_directory
directory
output"] == 1 === relationship{" "} relationship == N === Document["Document

path
relative_path
collection
date"]

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.

Articles in this category

Jekyll basic concepts Jekyll Configuration File Options Understanding Jekyll Posts Accessing Specific Items From Data Files In Jekyll What Are The Supported Language Highlighters In Jekyll

Articles

This article is being referenced in:

Understanding How Collections Work Jekyll basic concepts

Table of Contents