Pencil.Blog

This module provides a standard way of building and generating blog posts. Check out the Blog example here. You can also follow the blogging tutorial 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

Where yyyy-mm-dd should be something like 2019-12-30. This isn't used for anything other than to keep each post ordered in the directory, for your ease of viewing.

Each post is expected to have a preamble that has at least postTitle and date defined. The date set in the preamble is used as the sort order of the blog posts. The other variables are optional.

<!--PREAMBLE
postTitle: "The Meaning of Life"
date: 2010-01-30
draft: true
tags:
  - philosophy
-->

You can mark a post as a draft via the draft variable, so that it won't be loaded when you call loadPosts. You can also set the post's tags using, as seen above in tags. Then, use loadPosts 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 "layout.html"
postLayout <- load "blog-post.html"
posts <- loadPosts "blog/"
render (fmap (layout <|| postLayout <|) posts)

Documentation

loadPosts :: 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 <- loadPosts "blog/"

postUrl :: FilePath -> FilePath

Rewrites file path for blog posts.

postUrl "/blog/2011-01-01-post-title.html"
-- "/blog/1-post-title.html/"

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.

For example, if the page's preamble has postTitle: "The Meaning of Life", then the snippet below will insert a title variable with the value "The Meaning of Life - My Awesome Website":

injectTitle "My Awesome Website" post

Tags

You can add tags to blog posts.

type Tag = Text

Like, you know, a hashtag. Wraps a text.

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

Finds all the tags from the given pages, and generates a page for each tag found. Each tag page has a variable "posts" containing all pages that have the tag.

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

tagPages <- buildTagPages pages

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 _ -> "blog/tags/" ++ unpack tag ++ "/")
              posts

injectTags :: HashMap Tag Page -> Page -> Page

Injects the tag map (usually generated by buildTagPages or buildTagPagesWith) into the page's environment as the variable tags, which is an VEnvList.