grunt-pages

grunt-pages

Grunt task to create pages using markdown and templates

Prerequisites

This Grunt task uses pygments which requires Python to be installed.

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: 'posts',
    dest: 'dev',
    layout: 'src/layouts/post.jade',
    url: '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. The metadata format is a JavaScript Object, and here is an 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. If it is specified, it is used as a dateString when constructing a Date object in JavaScript, and must be in a parseable format. If unspecified, the post's date will be the result of constructing a Date object using the post's last modified time.

Syntax Highlighting

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

Draft Posts

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

Styling Headers

By default, grunt-pages generates header tags that include nested anchor tags with span's to allow for header section linking. Here is an example of the HTML that the above header would generate:

<h3>
  <a name="styling-headers" class="anchor" href="#styling-headers">
    <span class="header-link"></span>
  </a>
  "Styling Headers"
</h3>

The generated markup follows the same format as GitHub README's and it is recommended to reference Cabin theme's styling when trying to create header linking.

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.

Note: you can run grunt-pages with the --debug flag set to see all the data passed to templates for rendering.

url

Type: String

The URL of each post. The URL string takes variables as parameters using the :variable syntax. Variables 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 to optionally display it differently when linking to pages. All of the files in this folder are generated in the dest folder maintaining the same relative path from options.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 code.',
      url: 'http://chrisawren.com'
    }
  },
  posts: {
    src: 'posts',
    dest: 'dev',
    layout: 'src/layouts/post.jade',
    url: '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: '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. This page will not be rendered as a regular page if options.pageSrc is specified. Instead it will be rendered as the root paginated list page with the first post group instead of all the posts. 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 post content and other 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 list 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 options.pagination.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: 'Front end web development',
    tags: ['javascript', 'css'],
    content: '...'
  }, {
    title: 'Backbone.js',
    tags: ['javascript'],
    content: '...'
  }]
}, {
  id: 'css',
  posts: [{
    title: 'Style and Sass',
    tags: ['css'],
    content: '...'
  },{
    title: 'Front end web development',
    tags: ['javascript', '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 options.pageSrc folder when developing a grunt-pages configuration for multiple template engines.

Changelog

0.8.3 - Posts without the date specified now default to using the post's last modified time as the date thanks to @danburzo. Fixed bug where draft posts in nested folders weren't ignored properly.

0.8.2 - Temporarily reverted bug fix as caching issues resulted from code change.

0.8.1 - Fixed bug where draft posts in nested folders weren't ignored properly.

0.8.0 - Header tags are now rendered with a child span and anchor tag for linking into post sections. Removed support for YAML metadata. Added more robust metadata extraction for JavaScript object metadata. Added --debug flag to debug template data rendering. Standardized error logging to use the same format.

Breaking changes:

• Header tags are now rendered with a nested span and anchor tag for linking into post sections instead of being wrapped with anchor tags
• No more YAML metadata in posts

0.7.2 - Added support for Python 3 due to updating of node-pygmentize-bundled dependency.

0.7.1 - Wrong node_modules were pushed to npm. Pushed correct dependencies listed in package.json to fix bug.

0.7.0 - See breaking changes below.

Breaking changes:

• Pagination urls now have trailing index.html sections removed by default. The pagination url for a root list page is now '' instead of / to allow for base tags. Updated default pagination.url to pages/:id/ following new scheme that doesn't use index.html's.

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.