From ef055c18e515b48e24f9761bbf2cb46de34e23ce Mon Sep 17 00:00:00 2001
From: Tanya Bouman <tanyabouman@gmail.com>
Date: Sun, 2 Jun 2024 11:13:29 -0400
Subject: [PATCH] explain fields in `defaultContext` (#1031)

* explain fields in `defaultContext`

Hakyll.Web.Template.Context
- add examples to the fields
- add explanation about replacing `defaultContext` fields

'More on compilers: load, and templates' tutorial
- add `$title$` to the list of fields in `defaultContext`
- add explanation about replacing `defaultContext` fields

* Fix typo in web/tutorials/04-compilers.markdown

---------

Co-authored-by: Alexander Batischev <eual.jp@gmail.com>
---
 lib/Hakyll/Web/Template/Context.hs  | 25 ++++++++++++++++++++-----
 web/tutorials/04-compilers.markdown | 14 ++++++++++++++
 2 files changed, 34 insertions(+), 5 deletions(-)

diff --git a/lib/Hakyll/Web/Template/Context.hs b/lib/Hakyll/Web/Template/Context.hs
index 3baa1f7b5..8a60fdad2 100644
--- a/lib/Hakyll/Web/Template/Context.hs
+++ b/lib/Hakyll/Web/Template/Context.hs
@@ -247,7 +247,7 @@ snippetField = functionField "snippet" f
 --------------------------------------------------------------------------------
 -- | A context that contains (in that order)
 --
---     1. A @$body$@ field
+--     1. A @$body$@ 'bodyField'
 --
 --     2. Metadata fields
 --
@@ -256,6 +256,17 @@ snippetField = functionField "snippet" f
 --     4. A @$path$@ 'pathField'
 --
 --     5. A @$title$@ 'titleField'
+--
+-- This order means that all of the fields, except @$body$@,
+-- can have their values replaced by metadata fields of the same name.
+-- For example, a context from a file at @posts/foo.markdown@ has a default title
+-- @foo@.  However, with a metadata field:
+--
+-- > ---
+-- > title: The Foo Story
+-- > ---
+--
+-- The @$title$@ will be replaced with @The Foo Story@.
 defaultContext :: Context String
 defaultContext =
     bodyField     "body"     `mappend`
@@ -271,7 +282,7 @@ teaserSeparator = "<!--more-->"
 
 
 --------------------------------------------------------------------------------
--- | Constructs a 'field' that contains the body of the item.
+-- | Body of the item, that is, the main content of the underlying file
 bodyField :: String -> Context String
 bodyField key = field key $ return . itemBody
 
@@ -288,7 +299,8 @@ metadataField = Context $ \k _ i -> do
 
 
 --------------------------------------------------------------------------------
--- | Absolute url to the resulting item
+-- | Absolute url to the resulting item.  For an example item that produces a
+-- file @posts/foo.html@, this field contains "posts/foo.html"
 urlField :: String -> Context a
 urlField key = field key $ \i -> do
     let id = itemIdentifier i
@@ -297,13 +309,16 @@ urlField key = field key $ \i -> do
 
 
 --------------------------------------------------------------------------------
--- | Filepath of the underlying file of the item
+-- | Filepath of the underlying file of the item.  For an example
+-- underlying file @posts/foo.markdown@, this field contains
+-- "posts/foo.markdown"
 pathField :: String -> Context a
 pathField key = field key $ return . toFilePath . itemIdentifier
 
 
 --------------------------------------------------------------------------------
--- | This title 'field' takes the basename of the underlying file by default
+-- | Basename of the underlying file of the item.  For an example
+-- underlying file @posts/foo.markdown@, this field contains "foo"
 titleField :: String -> Context a
 titleField = mapContext takeBaseName . pathField
 
diff --git a/web/tutorials/04-compilers.markdown b/web/tutorials/04-compilers.markdown
index ce18f3b4c..50bef8f82 100644
--- a/web/tutorials/04-compilers.markdown
+++ b/web/tutorials/04-compilers.markdown
@@ -114,8 +114,22 @@ you to use:
 - `$body$` for the body of the page;
 - `$url$` for the destination URL of the page;
 - `$path$` for the original filepath of the page;
+- `$title$` for the basename of the original filepath of the page;
 - `$foo$` where foo is specified in the metadata.
 
+All of the fields, except `$body$`,
+can have their values replaced by metadata fields of the same name.
+For example, a context from a file at `posts/foo.markdown` has a default `$title$`
+of `foo`.  However, with metadata:
+
+```
+---
+title: The Foo Story
+---
+```
+
+The `$title$` will be replaced with `The Foo Story`.
+
 `$date$` is not provided by default. In the scaffold, we use the convenience
 context function `dateField`, which will parse an `Item`'s filename to check if
 it begins with a date. You can see how we add it in the definition of `postCtx`