From 602f5097d66b7dc01bd69df59aca9d3fc1aa8d45 Mon Sep 17 00:00:00 2001
From: adnano <me@adnano.co>
Date: Mon, 27 Jun 2022 15:05:54 -0400
Subject: [PATCH] docs: Document page .GetPage function

---
 docs/kiln.1.scd | 112 +++++++++++++++++++++++++++++++++---------------
 1 file changed, 78 insertions(+), 34 deletions(-)

diff --git a/docs/kiln.1.scd b/docs/kiln.1.scd
index 97006b6..e995581 100644
--- a/docs/kiln.1.scd
+++ b/docs/kiln.1.scd
@@ -207,7 +207,7 @@ Permalinks can be used to rewrite page paths. Permalinks are specified in the
 \[permalinks] table of the configuration file. Keys denote a path to a directory,
 and values use the Go templating language to rewrite the final path of pages in
 that directory. The templates have the same data that page templates have
-available to them (see *PAGE TEMPLATES*).
+available to them (see *PAGE VARIABLES*).
 
 The following configuration will rewrite the paths of pages in the content/blog
 directory to /YYYY/MM/DD/slug. For example, the file
@@ -435,84 +435,128 @@ Example feed configuration:
 
 Templates have certain data and functions available to them.
 
-## SITE METADATA
+## SITE VARIABLES
 
-Site metadata contains the following data:
+The following site-wide variables are available:
 
-*Title*
+*.Title*
 	The title of the site.
 
-*Params*
+*.Params*
 	Extra parameters specified in configuration.
 
-*Generated*
+*.Generated*
 	Site generation time.
 
-*Root*
-	The root page of the site.
+*.Root*
+	The root page of the site. See *PAGE VARIABLES*.
 
-Site metadata can be accessed from templates with the *site* function. See
+Some of these variables are defined in your site's configuration. See
+*CONFIGURATION*.
+
+Site variables can be accessed from templates with the *site* function. See
 *TEMPLATE FUNCTIONS*.
 
-To configure these variables, see *CONFIGURATION*.
+## PAGE VARIABLES
 
-## PAGE TEMPLATES
+The following page variables are available:
 
-Page and index templates are provided with the following data:
-
-*Title*
+*.Title*
 	The title of the page
 
-*Date*
+*.Date*
 	The date of the page
 
-*Weight*
+*.Weight*
 	The weight of the page
 
-*Path*
+*.Path*
 	The path to the page
 
-*URL*
+*.URL*
 	The URL of the page. If no base URL is configured, it is equivalent to
-	*Path*.
+	*.Path*.
 
-*FilePath*
+*.FilePath*
 	The path of the page file or directory relative to the content directory
 
-*Content*
+*.Content*
 	The contents of the page
 
-*Params*
+*.Params*
 	Extra parameters specified in frontmatter
 
-*Prev*
+*.Prev*
 	The previous page in sorted order
 
-*Next*
+*.Next*
 	The next page in sorted order
 
-*Pages*
+*.Pages*
 	List of pages in this directory
 
-*Dirs*
+*.Dirs*
 	List of subdirectories in this directory
 
-## FEED TEMPLATES
+Some of these variables are defined in page frontmatter. See *FRONTMATTER*.
 
-Feed templates are provided with the following data:
+Page variables can be accessed from page and index templates.
 
-*Title*
-	Title of the feed
+## PAGE FUNCTIONS
 
-*Path*
+The following page functions are available:
+
+*.GetPage* _path_
+	Retrieves the page in this directory with the given _path_, which may be
+	relative or absolute.
+
+	Example:
+
+	```
+	{{/* Retrieve a directory relative to the root directory
+		and iterate over its pages */}}
+	{{ with site.Root.GetPage "/blog" }}
+		{{ range .Pages }}
+			{{ .Title }}
+		{{ end }}
+	{{ end }}
+
+	{{/* Retrieve a directory relative to the current directory
+		and iterate over its pages */}}
+	{{ with .GetPage "posts" }}
+		{{ range .Pages }}
+			{{ .Title }}
+		{{ end }}
+	{{ end }}
+
+	{{/* Retrieve a page relative to the current directory */}}
+	{{ with .GetPage "posts/hello-world.gmi" }}
+		{{ .Title }}
+	{{ end }}
+	```
+
+Page functions can be accessed from page and index templates.
+
+## FEED VARIABLES
+
+The following feed variables are available:
+
+*.Title*
+	The title of the feed
+
+*.Path*
 	The path to the feed directory
 
-*URL*
+*.URL*
 	The URL of the feed directory
 
-*Pages*
+*.Pages*
 	List of pages in this feed
 
+Some of these variables are defined in feed configuration. See *FEEDS*.
+
+Feed variables can be accessed from feed templates.
+
 ## PARTIAL TEMPLATES
 
 Partial templates can be placed in the templates/\_partials directory.
@@ -644,7 +688,7 @@ All templates have the following functions available to them:
 	Encapsulates a known safe URL or URL substring.
 
 *site*
-	Returns site metadata (see *SITE METADATA*).
+	Returns site information (see *SITE VARIABLES*).
 
 *slice* _list_, _args..._
 	slice returns the result of slicing its first argument by the