diff --git a/docs/kiln.1.scd b/docs/kiln.1.scd
index db999f5..427f9ba 100644
--- a/docs/kiln.1.scd
+++ b/docs/kiln.1.scd
@@ -80,14 +80,58 @@ Example:
 
 The following keys are supported:
 
-[[ *Key*
-:[ *Description*
-|  title
-:  Page title
-|  date
-:  Page date
-|  params
-:  Extra parameters to be passed to templates
+*title*
+	The title of the page.
+
+	Example:
+
+	```
+	---
+	title: My first post
+	---
+	```
+
+*date*
+	The date of the page. Pages are sorted by date in reverse order, so newer
+	pages will be placed above older pages.
+
+	Example:
+
+	```
+	---
+	date: 2021-05-21
+	---
+	```
+
+*weight*
+	The weight of the page. Pages are sorted by weight in increasing order, so
+	pages with a smaller weight will be placed above pages with a larger weight.
+
+	Example:
+
+	```
+	---
+	weight: 1
+	---
+	```
+
+*params*
+	Specifies extra parameters to be provided to templates.
+
+	Example:
+
+	```
+	---
+	params:
+	  key: value
+	---
+	```
+
+## SORTING
+
+Pages are sorted automatically. Pages are first ordered by weight in increasing
+order, then by date from newest to oldest, and then by filename in alphabetical
+order.
 
 # TEMPLATES DIRECTORY