Add documentation for pagination

See #750

2 files changed, 95 insertions, 1 deletions

diff --git a/docs/content/extras/pagination.md b/docs/content/extras/pagination.md
new file mode 100644
index 000000000..5d27765a1
--- /dev/null
+++ b/docs/content/extras/pagination.md
@@ -0,0 +1,94 @@
+---
+aliases:
+- /doc/pagination/
+date: 2014-01-01
+menu:
+  main:
+    parent: extras
+next: /extras/highlighting
+prev: /extras/shortcodes
+title: Pagination
+weight: 80
+---
+
+Hugo supports pagination for the home page, sections and taxonomies.
+
+## Configuration
+
+Pagination can be configured in the site configuration (e.g. `config.toml`):
+
+* `Paginate` (default `0`) 
+* `PaginatePath` (default `page`)
+
+Setting `Paginate` to a positive value will split the list pages for the home page, sections and taxonomies into chunks of that size.[^lazy] `PaginatePath` is used to adapt the `Url` to the pages in the paginator (the default setting will produce urls on the form `/page/1/`. 
+
+## List the pages
+
+**A `.Paginator` is provided to help building a pager menu. This is only relevant for the templates for the home page and the list pages (sections and taxonomies).**  
+
+There are two ways to configure and use a `.Paginator`:
+
+1. The simplest way is just to call `.Paginator.Pages` from a template. It will contain the pages for *that page* .
+2. Select a sub-set of the pages with the available template functions and pass the slice to `.Paginate`, i.e. `{{ range (.Paginate (where .Data.Pages "Type" "post")).Pages }}`
+
+For a given **Node**, it's one of the options above. The `.Paginator` is static and cannot change once created.
+
+## Build the navigation
+
+The `.Paginator` contains enough information to build a paginator interface. 
+
+The easiest way to add this to your pages is to include the built-in template (with `Bootstrap`-compatible styles):
+
+```
+{{ template "_internal/pagination.html" . }}
+```
+
+**Note:** If you use any filters or sorting functions to create your `.Paginator` **and** you want the navigation buttons to be shown before the page listing, you must create the `.Paginator` before it's used:
+
+```
+{{ $paginator := .Paginate (where .Data.Pages "Type" "post") }}
+{{ template "_internal/pagination.html" . }}
+{{ range $paginator.Pages }}
+   {{ .Title }}
+{{ end }}
+```
+
+Without the where-filter, the above is simpler:
+
+```
+{{ template "_internal/pagination.html" . }}
+{{ range .Paginator.Pages }}
+   {{ .Title }}
+{{ end }}
+```
+
+If you want to build custom navigation, you can do so using the `.Paginator` object:
+
+* `PageNumber`: The current page's number in the pager sequence
+* `Url`: The relative Url to the current pager
+* `Pages`: The pages in the current pager
+* `NumberOfElements`: The number of elements on this page
+* `HasPrev`: Whether there are page(s) before the current
+* `Prev`: The pager for the previous page
+* `HasNext`: Whether there are page(s) after the current
+* `Next`: The pager for the next page
+* `First`: The pager for the first page
+* `Last`: The pager for the last page
+* `Pagers`: A list of pagers that can be used to build a pagination menu
+* `PageSize`: Size of each pager
+* `TotalPages`: The number of pages in the paginator
+* `TotalNumberOfElements`: The number of elements on all pages in this paginator
+
+## Additional information
+
+The pages are built on the following form (`BLANK` means no value):
+
+```
+[SECTION/TAXONOMY/BLANK]/index.html
+[SECTION/TAXONOMY/BLANK]/page/1/index.html => redirect to  [SECTION/TAXONOMY/BLANK]/index.html
+[SECTION/TAXONOMY/BLANK]/page/2/index.html
+....
+```
+
+[^lazy]: The generation of the pagination pages for sections, taxonomies and home page is *lazy* -- they will not be created if not referenced by a `.Paginator`.
+
diff --git a/docs/content/extras/shortcodes.md b/docs/content/extras/shortcodes.md
index 44eadcc77..be8258a97 100644
--- a/docs/content/extras/shortcodes.md
+++ b/docs/content/extras/shortcodes.md
@@ -5,7 +5,7 @@ date: 2013-07-01
 menu:
   main:
     parent: extras
-next: /extras/highlighting
+next: /extras/pagination
 prev: /extras/permalinks
 title: Shortcodes
 weight: 80