diff --git a/README.md b/README.md
index b720d27..ff1f10a 100644
--- a/README.md
+++ b/README.md
@@ -36,18 +36,47 @@ dst/               Site destination
 Running `kiln` takes the contents in `src`, runs them through the templates in
 `templates`, and writes the result to `dst`.
 
-## Pages
+## Permalinks
+
+Every page and directory in the site is assigned a path and a permalink.
+Paths are relative and point to the source file.
+Permalinks are absolute and point to the destination file.
+
+Examples:
+
+```
+file:      src/posts/2020-09-22-hello-world.gmi
+path:      posts/2020-09-22-hello-world.gmi
+permalink: /posts/hello-world.gmi
+
+directory: src/posts/
+path:      posts
+permalink: /posts/
+```
+
+## Templates
+
+Templates are located in the `templates` directory.
+There are currently two supported templates:
+
+- `page.gmi`: The template used for pages
+- `directory.gmi`: The template used for directories
+
+If `page.gmi` does not exist, page files will not be created.
+If `directory.gmi` does not exist, directory index files will not be created.
+
+### Page templates
 
 Page templates are provided with the following information:
 
 - `Title`: The title parsed from the first heading in the file
-- `Date`: The date parsed from the filename (e.g. `2020-09-22-hello-world.gmi`)
+- `Date`: The date parsed from the filename
 - `Path`: Relative path to the page
 - `Permalink`: Permalink to the page
-- `Content`: The contents of the file (including the title)
+- `Content`: The contents of the page (excluding the title)
 
 Pages can specify dates in their filenames. kiln will recognize the date and
-remove it from the permalink.
+remove it from the permalink. See [Permalinks](#permalinks) for an example.
 
 Pages can also specify titles in their content. kiln will parse and remove the
 title from the content. Example:
@@ -69,7 +98,7 @@ Content:
 This is some content.
 ```
 
-## Directories
+### Directory templates
 
 Directory templates are provided with the following information:
 
@@ -79,6 +108,7 @@ Directory templates are provided with the following information:
 - `Directories`: The subdirectories of this directory
 
 Directory templates are written to `index.gmi` in the corresponding directory.
+
 Example:
 
 ```
@@ -94,36 +124,3 @@ $ cat dst/posts/index.gmi
 => /posts/post-1.gmi
 => /posts/post-2.gmi
 ```
-
-## Templates
-
-Templates are located in the `templates` directory.
-
-There are currently two supported templates:
-
-- `page.gmi`: The template used for pages
-- `directory.gmi`: The template used for directories
-
-If `page.gmi` does not exist, page files will not be created.
-If `directory.gmi` does not exist, directory index files will not be created.
-
-## Permalinks
-
-Every page and directory in the site is assigned a path and a permalink.
-
-```
-file:      src/posts/2020-09-22-hello-world.gmi
-path:      posts/2020-09-22-hello-world.gmi
-permalink: /posts/hello-world.gmi
-```
-
-Paths are relative and point to the source file.
-Permalinks are absolute and point to the destination file.
-
-Here is an example of a directory:
-
-```
-directory: src/posts/
-path:      posts
-permalink: /posts/
-```