diff --git a/content/templates/list.md b/content/templates/list.md
index 36ababff6..c4f20d986 100644
--- a/content/templates/list.md
+++ b/content/templates/list.md
@@ -237,6 +237,18 @@ your list templates:
     </li>
     {{ end }}
 
+### Order by Parameter
+Order based on the specified frontmatter parameter. Pages without that
+parameter will use the site's `.Site.Params` default. If the parameter is not
+found at all in some entries, those entries will appear together at the end
+of the ordering.
+
+The below example sorts a list of posts by their rating.
+
+    {{ range (.Data.Pages.ByParam "rating") }}
+      <!-- ... -->
+    {{ end }}
+
 ### Reverse Order
 Can be applied to any of the above. Using Date for an example.