Creating a blog post

Creating a blog post is a lot like creating a page, only you create the text file in the posts folder instead of pages.

Naming conventions

There are 3 ways of organizing the posts folder: flat, shallow or hierarchical. By default PieCrust uses the flat mode. You can change the mode in the site configuration using the site/posts_fs setting.

Flat organization

In flat mode, all blog posts are HTML files in the posts folder that follow this naming convention:

<year>-<month>-<day>_<slug>.html

Here’s an example:

posts
 |- 2010-08-23_why-i-love-bacon.html

By default, that article would be accessible at http://domain.com/2010/08/23/why-i-love-bacon, although you can also change the URL format of blog posts in the site configuration.

This organization is good for blogs that don’t have a lot of updates.

Shallow organization

In shallow mode, the posts folder has sub-folders for each year, and those have all the posts for that year using the following convention:

<year>/<month>-<day>_<slug>.html

For example:

posts
 |- 2010
     |- 08-23_why-i-love-bacon.html

This organization is good for blogs with only a couple updates per month.

Hierarchical organization

In hierarchical mode, the year and month of a blog post are specified by the sub-folders in which they reside:

<year>/<month>/<day>_<slug>.html

For example:

posts
 |- 2010
     |- 08
         |- 23_why-i-love-bacon.html

This organization is good for blogs with quite a lot of articles.

Page breaks

When a page displays a list of blog posts, you sometimes don’t want to put the complete posts texts in there — instead, you only want the introduction of the post to be used. You can “cut” a post in two by inserting one of the “page break” tags:

<!-- more -->
<!-- break -->
<!-- pagebreak -->

Any of these tags would tell the pagination system to only take whatever comes before that tag when a post is shown in a list. See the pagination documentation for more info.

Configuration values

In addition to the usual page configuration values, blog posts can define a few useful things:

• time: Use this to specify a time of day for when the post was written (e.g. “12:45:02”). PieCrust will use it to expose the correct date and timestamp variables to the template engine.

• tags: Use this to add tags to a post, so that it appears in tag listings. This should be an array, like so: tags: [ food, cooking, fun ].

• category: Use this to put this post into one category, so that it appears in category listings.

Other useful variables to define are author or summary, although PieCrust wouldn’t do anything special with those — it’s just that they would be commonly used by pages showing those posts.