grunt-pages

Grunt task to create pages using markdown and templates

npm install grunt-pages
2 downloads in the last day
12 downloads in the last week
159 downloads in the last month

grunt-pages

Grunt task to create pages using markdown and templates

NPM version Dependency Status Travis Status

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. Posts also have access to other posts via the posts array, and know about their currentIndex within the array so that they can optionally create navigation to nearby posts. 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 || Function

The URL format of each post. When specified as a string, the url takes variables as parameters using the :variable syntax. Variables specified in the url are required in each post's metadata. URLs with a trailing / will generate posts as index.html files inside of the URL's folder.

You can also specify the url as a function which receives a post's metadata and grunt options object and returns the post's url. Note that the post metadata also includes the sourcePath of the post and lastModified time. This is used to maintain legacy post urls when migrating from another static site tool and to account for post titles that have all special characters(foreign languages).

Here is an example config which demonstrates how to implement the url as a function:

pages: {
  customURL: {
    src: 'posts',
    dest: 'dist',
    url: function (post, options) {
      // use post source path and apply default post url formatting
      return options.formatPostUrl(post.sourcePath.replace('.md', '/'));
    }
  }
}

Parsed posts are cached in the .grunt/grunt-pages folder based on the lastModified time to improve the task run time.

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.numPosts

Type: Number Default: 10

Number of posts to output in the RSS feed. This is used to avoid hitting a max file size limit.

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 options.pagination.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 options.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 options.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.10.1 - url can now be specified as a function to allow for foreign language post titles and to support legacy URLs for those migrating to grunt-pages from another static site tool.

0.10.0 - Added options.rss.numPosts option to determine the number of posts included in the RSS feed, defaulting to 10. Header links now use the same URL formatting function as post URLs.

Breaking changes:

  • The generated RSS feed now uses the first 10 posts(after sorting) instead of all of them to prevent a max file size error in RSS readers.
  • Header links now use the same URL formatting function as post URLs.

0.9.1 - Fixed bug where the options.pagination.listPage wasn't properly ignored for certain filenames.

0.9.0 - Posts now have access to their currentIndex within the posts array for navigating between nearby posts. Parsed posts are now cached in the .grunt/grunt-pages folder instead of node_modules/grunt-pages to provide more visibility and follow Grunt conventions. Header anchor tags now have correct attribute spacing thanks to @gmarty. Improved template debugging by printing data passed to template when an error is encountered. Reduced --debug output for post content to allow for easier debugging.

Breaking changes:

  • Parsed posts are now cached in the .grunt/grunt-pages folder instead of node_modules/grunt-pages.
  • Jade template output is no longer pretty printed unless --debug is specified.
  • Posts no longer have access to the post dest property which was mistakenly leaked to the template.

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.

npm loves you