From bc60df6d26962c2182d2e571a2b157c849f3d0d1 Mon Sep 17 00:00:00 2001
From: Armin Ronacher <armin.ronacher@active-4.com>
Date: Sat, 26 Dec 2015 20:48:05 +0100
Subject: [PATCH] Added sort key and guide on it

---
 .../docs/api/db/types/sort-key/contents.lr    | 21 ++++++++
 content/docs/guides/page-order/contents.lr    | 51 +++++++++++++++++++
 2 files changed, 72 insertions(+)
 create mode 100644 content/docs/api/db/types/sort-key/contents.lr
 create mode 100644 content/docs/guides/page-order/contents.lr

diff --git a/content/docs/api/db/types/sort-key/contents.lr b/content/docs/api/db/types/sort-key/contents.lr
new file mode 100644
index 00000000..44c1dc17
--- /dev/null
+++ b/content/docs/api/db/types/sort-key/contents.lr
@@ -0,0 +1,21 @@
+title: sort_key
+---
+summary: An integer type specific for sorting.
+---
+type: type
+---
+body:
+
+The `sort_key` type is similar to the `integer` type which is one of the most
+basic ones in Lektor.  It can store arbitrary natural numbers both negative and
+positive.  It's intended for giving pages a sort order.  The reason it's a
+special type is that future versions of Lektor can take advantage of this to
+implement a widget for ordering.
+
+## Field Usage
+
+```ini
+[fields.sort_key]
+label = Sort order
+type = sort_key
+```
diff --git a/content/docs/guides/page-order/contents.lr b/content/docs/guides/page-order/contents.lr
new file mode 100644
index 00000000..3b0420eb
--- /dev/null
+++ b/content/docs/guides/page-order/contents.lr
@@ -0,0 +1,51 @@
+title: Page Order
+---
+summary: How to get your pages ordered.
+---
+body:
+
+Pages can generally have an order defined.  This order comes from the
+configuration of children in the parent model or can be explicitly provided.
+This page guides you through all the different options you have.
+
+## Default Configuration
+
+The most common way to get order into your pages is the configuration for
+children.  This way an order can be defined that is used by default for any
+query involving the children of a page.  So what can you order by?  You can
+order by any field you want.  For instance to order by the name of a page
+you can do this:
+
+```ini
+[children]
+model = project
+order_by = name
+```
+
+This will automatically order the `.children` query by the name of a project.
+You can define more than one ordering.  For instance you could order blog
+posts by dates in decreasing order and secondarily by the blog title:
+
+```ini
+[children]
+model = blog-post
+order_by = -pub_date, title
+```
+
+A minus sign as prefix reverses the order.
+
+## Specific Order
+
+But what to do if you want to order something specifically?  In that case you
+can use the [sort_key :ref](../../api/db/types/sort-key/) type and configure
+that:
+
+```ini
+[children]
+model = doc-page
+order_by = sort_key
+```
+
+Currently you need to explicitly give numbers in this field but future versions
+of Lektor will provide support for automatically reordering them in the admin
+panel.