grunt-pages

grunt-pages

Grunt task to create pages using markdown and templates

Prerequisites

This Grunt task uses pygments, which relies on Python version 2.7.x.

Please note that grunt-pages will not run on the 3.x branch of Python

Getting Started

If you haven't used grunt before, be sure to check out the Getting Started guide, as it explains how to create a gruntfile as well as install and use grunt plugins. Once you're familiar with that process, install this plugin with this command:

npm install grunt-pages --save-dev

Then add this line to your project's Gruntfile.js gruntfile:

grunt.loadNpmTasks('grunt-pages');

Documentation

Sample config

Here is a sample config to create a blog using grunt-pages:

pages: {
  options: {
    pageSrc: 'src/pages'
  },
  posts: {
    src: 'src/posts',
    dest: 'dev',
    layout: 'src/layouts/post.jade',
    url: 'blog/posts/:title/'
  }
}

Authoring posts

Post Format

Posts are written in markdown and include a metadata section at the top to provide information about the post. There are two accepted metadata formats, YAML and a JavaScript object. Here is a YAML example:

----
title:   The Versace Sofa Thesis Vol. I
date:    2010-10-4
author:  Pusha T
----

The YAML data is parsed into a JavaScript object and passed to the post's template to be rendered. Check out js-yaml's site to learn more about how the translation works.

Here is a JavaScript object example:

{
  title: "Art Ballin': Explorations in New-Weird-American Expressionism",
  date: "2013-2-22",
  author: "Highroller, Jody"
}

The only property that is not interpreted literally is the date. It is used as a dateString when constructing a Date object in JavaScript, and must be in a parseable format. For both YAML and JavaScript object metadata, the JavaScript Date object is available in the layout.

Syntax Highlighting

For adding code to your posts, grunt-pages has GitHub flavoured markdown syntax highlighting using pygments.

Draft Posts

To make a post a draft, simply prefix its filename with a _. These posts will not be rendered or available in list pages.

Required properties

src

Type: String

The directory where the source posts are located.

dest

Type: String

The directory where pages are generated.

layout

Type: String

The jade or ejs layout template used for each post. The post metadata will be stored in a post object to be rendered in the layout template. Here is an example post layout template.

url

Type: String

The url of each post. The url string takes variables as parameters using the :variable syntax. Variable(s) specified in the url are required in each post's metadata. Urls ending with a trailing / will generate posts as index.html files inside of the url's folder.

Options

pageSrc

Type: String

The folder where the ejs or jade source pages of your website are located. These pages have access to each post's content and metadata properties via a posts array. Additionally, pages have access to their own filename(without extension) via the currentPage variable. All of the files in this folder are generated in the dest folder maintaining the same relative path from pageSrc.

data

Type: Object || String

A JavaScript object or the location of a JSON file which is passed as data to templates. This option is primarily used to specify config that is shared across all pages. It is available in page and post templates via the data object.

sortFunction

Type: Function

Default: Sort by date descending

function (a, b) {
  return b.date - a.date;
}

A compare function used by Array.sort to sort posts.

formatPostUrl

Type: Function

Default:

function (url) {
  return url
    .toLowerCase() // change everything to lowercase
    .replace(/^\s+|\s+$/g, '') // trim leading and trailing spaces
    .replace(/[_|\s|\.]+/g, '-') // change all spaces, periods and underscores to a hyphen
    .replace(/[^a-z\u0400-\u04FF0-9-]+/g, '') // remove all non-cyrillic, non-numeric characters except the hyphen
    .replace(/[-]+/g, '-') // replace multiple instances of the hyphen with a single instance
    .replace(/^-+|-+$/g, ''); // trim leading and trailing hyphens
}

A function that takes a url as a parameter and returns a formatted url string. This is primarily used to remove special characters and replace whitespace.

rss

Type: Object

An object containing config for RSS feed generation.

All options accepted by dylang/node-rss are supported, with notable options listed below.

Here is a sample config to create a blog with an RSS feed using grunt-pages:

pages: {
  options: {
    pageSrc: 'src/pages',
    rss: {
      author: 'Chris Wren',
      title: 'Chris Wren\'s Blog',
      description: 'A blog about software, music, and commerce.',
      url: 'http://chrisawren.com'
    }
  },
  posts: {
    src: 'src/posts',
    dest: 'dev',
    layout: 'src/layouts/post.jade',
    url: 'blog/posts/:title/'
  }
}

rss.url

Type: String

The URL of your site.

rss.author

Type: String

The feed owner. Also used as managingEditor and webMaster if those options are not specified.

rss.title

Type: String

The title of the feed.

rss.description

Type: String

Optional. Short description of the feed.

rss.path

Type: String

Optional. The path of the file to store the RSS XML in. This is specific to grunt-pages and is not part of dylang/node-rss.

pagination

Type: Object || Array

Object or an array of objects containing config for pagination. This option generates paginated list pages which each contain a specified group of posts.

Config using the default pagination scheme

pages: {
  options: {
    pagination: {
      postsPerPage: 3,
      listPage: 'src/layouts/listPage.jade'
    }
  },
  posts: {
    src: 'src/posts',
    dest: 'dev',
    layout: 'src/layouts/post.jade',
    url: 'posts/:title/'
  }
}

This config will generate paginated list pages by grouping the specified number of posts per page and using the default url scheme specified in the pagination.url parameter.

pagination.postsPerPage

Type: Number

The number of posts each list page will contain.

pagination.listPage

Type: String

The location of the layout template which is used for each list page. Here is a sample listPage template. This template has access to the following variables:

posts

Type: Array of Objects

An array of post objects assigned to this page which each contain the content and metadata properties of the post.

pages

Type: Array of Objects

An array of page objects which each contain a url and id property.

currentIndex

Type: Number

A reference to the index of the page currently being rendered. This can be used to display the current page differently than the rest of the pages in a list, or to display links to the surrounding pages based on their position relative to the currentIndex.

pagination.url

Type: String Default: pages/:id/

The location of the generated list pages relative to the pagination.listPage. You can override this property to have a custom url scheme for list pages. You must have a :id variable in your url scheme which will be replaced by the page's id.

Config using a custom pagination scheme

To paginate in a custom manor, you can use the following parameter:

pagination.getPostGroups

Type: Function

Default: Group by postsPerPage

function (postCollection, pagination) {
var postsPerPage = pagination.postsPerPage;
    var postGroups = [];
    var postGroup;
    var i = 0;

    while ((postGroup = postCollection.slice(i * postsPerPage, (i + 1) * postsPerPage)).length) {
      postGroups.push({
        posts: postGroup,
        id: i
      });
      i++;
    }
    return postGroups;
}

This function returns an array of post groups to be rendered as list pages. It takes the posts array and pagination config object as parameters and is expected to return an array of postGroup objects which each contain the id of the group(to be used in the url) and the array of posts in the following format:

[{
  id: 'javascript',
  posts: [{
    title: 'ES6',
    tags: ['javascript'],
    content: '...'
  }, {
    title: 'Backbone.js',
    tags: ['javascript'],
    content: '...'
  }]
}, {
  id: 'css',
  posts: [{
    title: 'Style and Sass',
    tags: ['css'],
    content: '...'
  }]
}];

Here is a sample pagination config which paginates using the tags property of each post:

pages: {
  options: {
    pagination: {
      listPage: 'src/layouts/tagListPage.jade',
      getPostGroups: function (posts) {
        var postGroups = {};

        posts.forEach(function (post) {
          post.tags.forEach(function (tag) {
            tag = tag.toLowerCase();
            if (postGroups[tag]) {
              postGroups[tag].posts.push(post);
            } else {
              postGroups[tag] = {
                posts: [post]
              };
            }
          });
        });

        return grunt.util._.map(postGroups, function (postGroup, id) {
          return {
            id: id,
            posts: postGroup.posts
          };
        });
      }
    }
  },
  posts: {
    src: 'src/posts',
    dest: 'dev',
    layout: 'src/layouts/post.jade',
    url: 'posts/:title'
  }
}

templateEngine

Type: String

The file extension of the template engine to be used. This option filters template files in the pageSrc folder when developing a grunt-pages configuration for multiple template engines.

Changelog

0.6.1 - Removed accidental logging pushed to npm.

0.6.0 - Updated pagination urls to not have a leading /.

Breaking changes:

• Pagination urls will no longer have a leading / by default. This is a bug fix and the implementation now matches what is documented in the pagination.url API.

0.5.0 - Updated default post url regex to capture more cases thanks to @justinhelmer. Fixed bugs regarding normalizing the post dest and ignoring draft posts thanks to @justinhelmer.

Breaking changes:

• Post urls will potentially be altered because of the new regex. To update, you will have to provide redirects to altered post urls if you need to maintain them i.e. social media share buttons.

0.4.1 - .html excluded from post url :variable replacement.

0.4.0 - Altered post url to not automatically add .html to urls.

Breaking changes:

• Post urls will now require .html to be listed explicitly to be in the url. The recommended convention is to put each post in its own folder, like posts/:title/ so that a post with the title hello would be generated at posts/hello/index.html.

0.3.3 - Added lodash as a hard dependency.

0.3.2 - Added post caching for unmodified posts to speed up task.

0.3.1 - Added rss option to generates feeds thanks to @lazd.

0.3.0 - Altered pagination API to allow for custom pagination schemes.

Breaking changes:

• Paginated pages no longer have a currentPage as a property of the current page in the pages array, rather it is exposed as a global variable called currentIndex for easier accessibility.

0.2.5 - Fixed metadata parsing bug, added formatPostUrl option & added pagination.url option.

0.2.4 - Added sortFunction option & allowed for data option to take an object as a parameter.

0.2.3 - Ignored dotfiles, added error reporting for incorrect data JSON files, and added new header anchor link format.

0.2.2 - Used forked version of marked to enable header anchor links.

0.2.1 - Added support for _ prefixed draft posts and pages now receive their filename as a currentPage variable.

0.2.0 - Fixed templateEngine bug, changed pagination and data api.

0.1.0 - Added data option, added templateEngine option, added pagination option, and changed post data format to be a post object rather than global variables for each post property.

0.0.0 - Initial release.