grunt-pages-redux
v2.0.2
Published
Grunt task to create pages using markdown and templates
Downloads
14
Maintainers
Readme
grunt-pages-redux
Grunt task to create pages using markdown and templates
A fork of https://www.npmjs.com/package/grunt-pages
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-redux --save-dev
Then add this line to your project's Gruntfile.js
Gruntfile:
grunt.loadNpmTasks('grunt-pages-redux');
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: 'Blogging in my Cabin',
date: '2014-1-1',
author: 'Firstname Lastname'
}
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. Note that you can override this by implementing options.markedOptions.renderer.heading
.
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, EJS, or Handlebars 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.
Handlebars partials
Handlebars partials can be specified using the options.partials
property. This allows you to specify a file glob of partials to use in your layout and page templates. The partials are available as the basename of the partial file, so a file with the path src/layouts/partials/nav.hbs
would be referenced as {{> nav}}
Here is an example config which shows how to configure Handlebars partials:
target4: {
src: 'posts',
dest: 'dest4',
layout: 'src/layouts/post.hbs',
url: 'blog/posts/:title/',
options: {
partials: 'src/layouts/partials/**/*.hbs'
}
}
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.
Note: posts are not re-compiled when the grunt config changes, you can either run the task with the --no-cache
flag or delete the .grunt/grunt-pages
folder to force all posts to be re-built.
Options
pageSrc
Type: string
The folder where the jade, EJS, or Handlebars 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.
markedOptions
Type: function || object
You can configure how marked parses your markdown by overriding options here. Check out the marked options to see what you can alter. When options.markedOptions
is implemented as a function, it receives marked
as an argument so you can instantiate marked.Renderer
and override particular properties.
Note: all marked renderer methods are extened to have access to the current post
as an extra argument.
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: {
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/'
}
}
Required RSS properties
rss.url
Type: string
The URL of your site.
rss.title
Type: string
The title of the feed.
rss.description
Type: string
Short description of the feed.
Optional RSS properties
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.author
Type: string
The feed owner. Also used as managingEditor
and webMaster
if those options are not specified.
rss.path
Type: string
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 object
s
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 object
s
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'
}
}
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.
metadataValidator
Type: function
A function that takes an array of posts
as the first argument and the templateData
to be passed to posts as a second argument in order to determine if the supplied metadata is valid for the posts. This is helpful in catching issues when metadata is forgotten or invalid like having two posts with the same index
property when displaying posts in a list. It can also be used to record information about posts and add new information to templateData
for rendering in templates after posts have been processed.
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.11.2 - Add templateData
argument to metadataValidator
option.
0.11.1 - Fixed leading /
issue for post URLs. Added post.sourcePath
and post.lastModified
to template data. Added current post
as an extra argument to all marked renderer methods. Added metadataValidator
option to ensure metadata is proper for all posts. Added --no-cache
flag to invalidate caching when altering how posts are parsed.
0.11.0 - Fixed required RSS properties, now correctly matching the RSS spec, thanks to @rogeriopvl. Added Handlebars support with partials thanks to @thomasboyt. Updated to marked ~0.3.0 now supporting options.markedOptions
to configure any marked options that you desire.
Breaking changes:
options.rss.description
is now required, andoptions.rss.author
is not.- Updated to jade 1.0, check here for the 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 ofnode_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 topages/:id/
following new scheme that doesn't useindex.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 titlehello
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 thepages
array, rather it is exposed as a global variable calledcurrentIndex
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.