Pencil.Blog

Getting started

This module provides a standard way of building and generating blog posts. Check out the Blog example here.

To generate a blog for your website, first create a blog/ directory in your web page source directory.

Then, name your blog posts in this format:

yyyy-mm-dd-title-of-blog-post.markdown

The files in that directory are expected to have preambles that have at least postTitle and date defined. The other ones are optional.

<!--PREAMBLE
postTitle: "Behind Python's unittest.main()"
date: 2010-01-30
draft: true
tags:
  - python
-->

You can mark a post as a draft via the draft variable (it won't be loaded when you call loadBlogPosts), and add tagging (see below) via tags. Then, use loadBlogPosts to load the entire blog/ directory.

In the example below, layout.html defines the outer HTML structure (with global components like navigation), and blog-post.html is a generic blog post container that renders ${postTitle} as a header, ${date}, and ${body} for the post body.

layout <- load toHtml "layout.html"
postLayout <- load toHtml "blog-post.html"
posts <- loadBlogPosts "blog/"
render (fmap (layout <|| postLayout <|) posts)

loadBlogPosts :: FilePath -> PencilApp [Page]

Loads the given directory as a series of blog posts, sorted by the date PREAMBLE environment variable. Posts with draft: true are filtered out.

posts <- loadBlogPosts "blog/"

blogPostUrl :: FilePath -> FilePath

Rewrites file path for blog posts. /blog/2011-01-01-the-post-title.html => /blog/the-post-title/

injectTitle

Arguments

:: Text

Title prefix.

-> Page

-> Page

Given that the current Page has a postTitle in the environment, inject the post title into the title environment variable, prefixed with the given title prefix.

This is useful for generating the <title>${title}</title> tags in your container layout.

injectTitle "My Awesome Website" post

The above example may insert a title variable with the value "How to do X - My Awesome Website".

buildTagPagesWith

Arguments

:: FilePath

Partial to load for the Tag index pages

-> Text

Variable name inserted into Tag index pages for the list of Pages tagged with the specified tag

-> (Tag -> FilePath -> FilePath)

Function to generate the URL of the tag pages.

-> [Page]

-> PencilApp (HashMap Tag Page)

Build the tag index pages.

Given blog post Pages with tags variables in its PREAMBLE, builds Pages that contain in its environment the list of Pages that were tagged with that particular tag. Returns a map of tag of the tag index page.

tagPages <- buildTagPagesWith
              "tag-list.html"
              "posts"
              (tag _ -> "blogtags" ++ unpack tag ++ "/")
              posts

buildTagPages :: FilePath -> [Page] -> PencilApp (HashMap Tag Page)

Helper of buildTagPagesWith defaulting to the variable name posts, and the tag index page file path blog/tags/my-tag-name/.

tagPages <- buildTagPages pages

injectTagsEnv :: HashMap Tag Page -> Page -> Page

Inject the given tagging map into the given Page's environment, as the tags variable, whose value is a VEnvList.