The most important function for pagination. This function operates on a
list of Contexts (the pages), and basically just adds fields to them
by combining them with a custom page.
The following metadata fields will be added:
- $previous: A link to the previous page.
- $next: A link to the next page.
- $first: A link to the first page.
- $last: A link to the last page.
- $index: 1-based index of the current page.
- $length: Total number of pages.
When $previous or $next are not available, they will be just a label
without a link. The same goes for when we are on the first or last page for
$first and $last.