diff --git a/README.md b/README.md
index 4df4146..2bc08e1 100644
--- a/README.md
+++ b/README.md
@@ -124,6 +124,10 @@ You can also set the `template` variable to change which template will be used t
 Sections will also automatically pick up their subsections, allowing you to make some complex pages layout and
 table of contents.
 
+You can define how a section pages are sorted using the `sort_by` key in the front-matter. The choices are `date` (default), `order`
+and `none`. Pages that can be sorted will currently be silently dropped: the final page will be rendered but it will not appear in 
+the `pages` variable in the section template.
+
 A special case is the `_index.md` at the root of the `content` directory which represents the homepage. It is only there
 to control pagination and sorting of the homepage.