Contents in Jekyll

Content in Jekyll is either a post or a page. These content “objects” get inserted into one or more templates to build the final output for its respective static-page.

#####Working With Posts Posts and Pages Both posts and pages should be written in markdown, textile, or HTML and may also contain Liquid templating syntax. Both posts and pages can have meta-data assigned on a per-page basis such as title, url path, as well as arbitrary custom meta-data.

Creating a Post

Posts are created by properly formatting a file and placing it the _postsfolder.

Formatting A post must have a valid filename in the form YYYY-MM-DD-title.MARKUP and be placed in the _posts directory. If the data format is invalid Jekyll will not recognize the file as a post. The date and title are automatically parsed from the filename of the post file. Additionally, each file must have YAML Front-Matter prepended to its content. YAML Front-Matter is a valid YAML syntax specifying meta-data for the given file.

Order Ordering is an important part of Jekyll but it is hard to specify a custom ordering strategy. Only reverse chronological and chronological ordering is supported in Jekyll.

Since the date is hard-coded into the filename format, to change the order, you must change the dates in the filenames.

Tags Posts can have tags associated with them as part of their meta-data. Tags may be placed on posts by providing them in the post’s YAML front matter. You have access to the post-specific tags in the templates. These tags also get added to the sitewide collection.

Categories Posts may be categorized by providing one or more categories in the yml front matters. Categories offer more significance over tags in that they can be reflected in the URL path to the given post. Note categories in Jekyll work in a specific way. If you define more than one category you are defining a category hierarchy “set”. Example:

---
title :  Hello World
category : startup
---

or

---
title :  Hello World
categories : [startup, begin]
---

This defines the category hierarchy “startup/begin”. Note this is one category node in Jekyll. You won’t find “startup” and “begin” as two separate categories unless you define them elsewhere as singular categories.

#####Working With Pages Creating a Page Pages are created by properly formatting a file and placing it anywhere in the root directory or subdirectories that do not start with an underscore.

Formatting In order to register as a Jekyll page the file must contain YAML Front-Matter. Registering a page means: 1) that Jekyll will process the page and 2) that the page object will be available in the site.pages array for inclusion into your templates.

Categories and Tags Pages do not compute categories nor tags so defining them will have no effect.

Sub-Directories If pages are defined in sub-directories, the path to the page will be reflected in the url. Example:

people
└──bob
    └──essay.html

This page will be available at http://yourdomain.com/people/bob/essay.html

Recommended Pages

1) index.html You will always want to define the root index.html page as this will display on your root URL.

2) 404.html Create a root 404.html page and GitHub Pages will serve it as your 404 response.

3) sitemap.html Generating a sitemap is good practice for SEO.

4) about.html A nice about page is easy to do and gives the human perspective to your website.