Add pagination support for any ContentPage

[ryansobol]

Assume the following content pages in content/blog/:

$ tree content/blog/
content/blog/
├── 1.md
├── 2.md
├── 3.md
├── 4.md
├── 5.md
├── 6.md
├── 7.md
├── 8.md
├── 9.md
├── 10.md
├── 11.md
└── index.md

Also, assume content/blog/index.md contains the following header attribute:

$ cat content/blog/index.md

---
paginate: 3

---

When routing /blog/index or /blog/index?page=1, the ContentPage contains the following attributes:

page.paginator.previous     nil
page.paginator.current      1
page.paginator.next         2
page.paginator.ceiling      4
page.paginator.dividend     11
page.paginator.divisor      3
page.paginator.quotient     3
page.paginator.pages        An array of ContentPage instances for 1.md, 2.md, and 3.md

And when routing /blog/index?page=2, the ContentPage contains the following attributes:

page.paginator.previous     1
page.paginator.current      2
page.paginator.next         3
page.paginator.ceiling      4
page.paginator.dividend     11
page.paginator.divisor      3
page.paginator.quotient     3
page.paginator.pages        An array of ContentPage instances for 4.md, 5.md, and 6.md

And when routing /blog/index?page=3, the ContentPage contains the following attributes:

page.paginator.previous     2
page.paginator.current      3
page.paginator.next         4
page.paginator.ceiling      4
page.paginator.dividend     11
page.paginator.divisor      3
page.paginator.quotient     3
page.paginator.pages        An array of ContentPage instances for 7.md, 8.md, and 9.md

And when routing /blog/index?page=4, the ContentPage contains the following attributes:

page.paginator.previous     3
page.paginator.current      4
page.paginator.next         nil
page.paginator.ceiling      4
page.paginator.dividend     11
page.paginator.divisor      3
page.paginator.quotient     2
page.paginator.pages        An array of ContentPage instances for 10.md and 11.md

And when routing /blog/index?page=5 or /blog/index?page=-1 or /blog/index?page=anything_out_of_bounds, the Application should not find an appropriate ContentPage to render.

---

Here are some explicit take-aways given the above scenarios:

• The value of the paginate header attribute becomes the value of the page.paginator.divisor ContentPage attribute. It must be an integer greater than 0, otherwise an exception is raised.
• Given a valid paginate header attribute, the ContentPage's page.paginator logic should be based on its siblings, nephews, grand-nephews, etc. This means page.paginator.pages should contain every ContentPage within the directory and all sub-directories except the ContentPage that defined the paginate header attribute.
• The ContentPages are ordered alphabetically descending by file name.

In addition, the page.paginator object contains the following read-only attributes:

page.paginator.previous     The number of the previous page.
page.paginator.current      The number of the current page.
page.paginator.next         The number of the next page.
page.paginator.ceiling      The total number of pages.
page.paginator.dividend     The total number of ContentPages.
page.paginator.divisor      The maximum number of ContentPages available per page.
page.paginator.quotient     The number of ContentPages available for this page.
page.paginator.pages        The list of ContentPages available for this page.

See Jekyll's Pager and Pagination classes for example implementation logic.