From 34ac562ce4544cb481d286e3aa040f5ca14afc04 Mon Sep 17 00:00:00 2001
From: spf13 <steve.francia@gmail.com>
Date: Fri, 20 Dec 2013 18:11:49 -0500
Subject: [PATCH] Added documentation on ordering indexes, content and content
 within indexes

---
 docs/content/content/ordering.md | 79 ++++++++++++++++++++++++++++++++
 docs/content/indexes/ordering.md | 70 ++++++++++++++++++++++++++++
 2 files changed, 149 insertions(+)
 create mode 100644 docs/content/content/ordering.md
 create mode 100644 docs/content/indexes/ordering.md

diff --git a/docs/content/content/ordering.md b/docs/content/content/ordering.md
new file mode 100644
index 000000000..9379c6f50
--- /dev/null
+++ b/docs/content/content/ordering.md
@@ -0,0 +1,79 @@
+---
+title: "Ordering Content"
+date: "2013-07-01"
+linktitle: "Ordering"
+groups: ['content']
+groups_weight: 60
+---
+
+In Hugo you have a good degree of control of how your content can be ordered.
+
+By default, content is ordered by weight, then by date with the most recent date first.
+
+_Both the date and weight fields are optional._ 
+
+Unweighted pages appear at the end of the list.
+If no weights are provided (or if weights are the same) date will be used to sort. If neither are provided
+content will be ordered based on how it's read off the disk and no order is guaranteed.
+
+Alternative sorting is also available to order content by date (ignoring weight), length and reverse the order.
+
+## Assigning Weight to content
+
+    +++
+    weight = "4"
+    title = "Three"
+    date = "2012-04-06"
+    +++
+    Front Matter with Ordered Pages 3
+
+## Order by Weight -> Date (default)
+
+    {{ range .Data.Pages }}
+    <li>
+      <a href="{{ .Permalink }}">{{ .Title }}</a>
+      <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
+    </li>
+    {{ end }}
+
+## Order by Weight -> Date
+
+    {{ range .Data.Pages.ByWeight }}
+    <li>
+      <a href="{{ .Permalink }}">{{ .Title }}</a>
+      <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
+    </li>
+    {{ end }}
+
+
+## Order by Date
+
+    {{ range .Data.Pages.ByDate }}
+    <li>
+      <a href="{{ .Permalink }}">{{ .Title }}</a>
+      <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
+    </li>
+    {{ end }}
+
+## Order by Length
+
+    {{ range .Data.Pages.ByLength }}
+    <li>
+      <a href="{{ .Permalink }}">{{ .Title }}</a>
+      <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
+    </li>
+    {{ end }}
+
+## Reverse Order
+Can be applied to any of the above. Using Date for an example.
+
+    {{ range .Data.Pages.ByDate.Reverse }}
+    <li>
+      <a href="{{ .Permalink }}">{{ .Title }}</a>
+      <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
+    </li>
+    {{ end }}
+
+## Ordering Content Within Indexes
+
+Please see the [Index Ordering Documentation](/indexes/ordering/)
diff --git a/docs/content/indexes/ordering.md b/docs/content/indexes/ordering.md
new file mode 100644
index 000000000..b1952b4c5
--- /dev/null
+++ b/docs/content/indexes/ordering.md
@@ -0,0 +1,70 @@
+---
+title: "Ordering Indexes"
+date: "2013-07-01"
+linktitle: "Ordering"
+groups: ["indexes"]
+groups_weight: 60
+---
+
+Hugo provides the ability to both:
+
+ 1. Order the way the keys for an index are displayed
+ 2. Order the way indexed content appears
+
+
+## Ordering Indexes
+Indexes can be ordered by either alphabetical key or by the number of content pieces assigned to that key.
+
+### Order Alphabetically Example:
+
+       <ul>
+       {{ $data := .Data }}
+        {{ range $key, $value := .Data.Index.Alphabetical }}
+        <li><a href="{{ $data.Plural }}/{{ $value.Name | urlize }}"> {{ $value.Name }} </a> {{ $value.Count }} </li>
+        {{ end }}
+       </ul>
+
+### Order by Popularity Example:
+
+       <ul>
+       {{ $data := .Data }}
+        {{ range $key, $value := .Data.Index.ByCount }}
+        <li><a href="{{ $data.Plural }}/{{ $value.Name | urlize }}"> {{ $value.Name }} </a> {{ $value.Count }} </li>
+        {{ end }}
+       </ul>
+
+
+[See Also Index Lists](/indexes/lists/)
+
+## Ordering Content within Indexes
+
+Hugo uses both **Date** and **Weight** to order content within indexes.
+
+Each piece of content in Hugo can optionally be assigned a date.
+It can also be assigned a weight for each index it is assigned to.
+
+When iterating over content within indexes the default sort is first by weight then by date. This means that if the weights for two pieces of content are the same, than the more recent content will be displayed first. The default weight for any piece of content is 0.
+
+### Assigning Weight
+
+Content can be assigned weight for each index that it's assigned to.
+
+    +++
+    tags = [ "a", "b", "c" ]
+    tags_weight = 22
+    categories = ["d"]
+    title = "foo"
+    categories_weight = 44
+    +++
+    Front Matter with weighted tags and categories
+
+
+The convention is `indexname_weight`.
+
+In the above example, this piece of content has a weight of 22 which applies to the sorting when rendering the pages assigned to the "a", "b" and "c" values of the 'tag' index.
+
+It has also been assigned the weight of 44 when rendering the 'd' category.
+
+With this the same piece of content can appear in different positions in different indexes.
+
+Currently indexes only support the default ordering of content which is weight -> date.