docpad/docpad-plugin-paged — pull request #12 by ervwalter (2013-10-08 07:17:00+00:00)
Title: Add cleanurl, startingPageNumber, and pagePathPrefix options

This pull request has three enhancements in it that are all intertwined in the same block of 5-10 lines of code dealing with naming of the generated files. Because of the intertwined nature of the changes, I created a single pull request. Let me know if you prefer some other approach. I also attempted to update the README.md with some documentation, but if you don't like the way I documented the new options, let me know.

__Background__

I made all three of these options as part of getting this plugin to generate a file patterns that matched what I was looking for (which was driven mostly by what I had in my old octopress blog). In particular, my old blog's main index page had /index.html for the first page, /page/2/index.html for the next, /page/3/index.html for the next, etc...

There are three conceptual and reusable changes to make that happen:

__Clean Urls__

I added a cleanurl config option to this plugin to make it generate clean urls straight away. After some review of this plugin and the cleanurl plugin, this seemed like the cleaner approach (no pun intended). The alternative of trying to clean up the virtual documents after the fact in the cleanurl plugin seemed more messy.

When cleanurl = true, /archive.html, /archive.1.html, and /archive.2.html become /archive/index.html, /archive/1/index.html, and /archive/2/index.html

There is special case handling for any file named index.html (common for the top level blog index, for example). In that case, index.html, index.1.html, index.2.html become /index.html, /1/index.html, and /2/index.html

__Starting Page Number__

Normally, the first _extra_ page has a '1' in the name. In URLs, I found that to be somewhat confusing, because this file is actually the _second_ page. The startingPageNumber config option allows you to tell the plugin to start at 2 instead of one. So (with clean urls), you get /archive/, /archive/2/, /archive/3/ instead of /archive/, /archive/1/, /archive/2/.

__Page Path Prefix__

This is a document-specific metadata property. Particularly in the case of index.html, it may be preferable for the extra pages to not just be /2/, /3/, /4/, but rather to have some name in them. In my case, I set pagePathPrefix = 'page' and my index.html becomes: /, /page/2/, /page/3/, etc...

__Note:__ In all three cases, the default behavior is consistent with the behavior pre-pull request so these don't affect anything unless people opt-in to them.