From 58b5a1ac96686ba1a98b8dbeb586f9864d958b1e Mon Sep 17 00:00:00 2001
From: "Kevin C. Coram" <kcoram@gmail.com>
Date: Sat, 23 Nov 2019 14:33:41 -0500
Subject: [PATCH] Document Hugo templating approach

---
 README.md | 76 ++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 73 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 463f53b..8d19d73 100644
--- a/README.md
+++ b/README.md
@@ -29,12 +29,12 @@ hugo serve [ -D ] --themesDir ../..
 Most of the sample posts are intentionally set `draft: true` to allow for 
 testing few posts vs many posts.
 
-## Setup
+## Configuration
 
-As a very basic theme, there is very little to be configured in ones `config.toml` 
+As a very basic theme, there is very little to be configured via the `config.toml` 
 file.
 
-The layout files uses Hugo's `markdownify` pipe to display the `copyright` 
+The footer layout file uses Hugo's `markdownify` pipe to display the `copyright` 
 configuration setting, providing support both for HTML5 character escape
 sequences such as `&copy;` as well as markdwn formatting and links.
 
@@ -81,6 +81,12 @@ The chrome of the theme page organization is as follows:
             <!-- the list of pages goes. For single pages, this is where -->
             <!-- the content of the page markdown file goes.             -->
         </section>
+        <footer>
+            <!-- The page footer. For list sections, this is where the   -->
+            <!-- pagination controls can go. For single pages, this is   -->
+            <!-- where auther attribution and/or prev/next page controls -->
+            <!-- could go.                                               -->
+        </footer>
     </main>
     <footer>
         <!-- The Site Footer, for copyright information etc. -->
@@ -99,3 +105,67 @@ in document outlines structured as:
       1. Sub-header from content
    2. Second Header from Content
 
+### Hugo Templating
+
+The template layout files make heavy use of Hugo's 
+[base and block constructs](https://gohugo.io/templates/base/), as can be seen
+in [baseof.html](layouts/_default/baseof.html).
+
+#### title
+
+This block is used for generating the `<title>....</title>` markup for the
+rendered page and defaults to using the `title` configuration from `comfig.toml`.
+The [list](layouts/_default/list.html) and [single](layouts/_default/single.html)
+templates add the page title, to facilitate generating a unique title for every
+page.
+
+#### site-header
+
+This block is for providing a site banner that will appear at the top of every page,
+and matches with the primary `<header>...</header>` definition from the semantic 
+organization, above.
+
+The default site-header block displays the [header.html](layouts/partials/header.html)
+partial.
+
+#### site-menu
+
+This block is for providing a site-level navigation, which also appears at the
+top of every page. It renders in the `<nav>...</nav>` block within the primary
+header.
+
+The default site-meny block displays the [site-menu](layouts/partials/site-menu.html)
+partial.
+
+#### content-header
+
+This block is for providing a header for the specific page, matching with the
+header block inside the `<main>....<\main>` definition from the semantic
+organization. The [list](layouts/_default/list.html) and 
+[single](layouts/_default/single.html) templates display the page title as 
+a `<h1>...</h1>` level header.
+
+#### content
+
+This block is for the content of the page.
+
+For [list](layouts/_default/list.html) pages, the content from the section's
+`_index.md` will be rendered, followed by a list of all of the pages within
+the section, using the [summary](layouts/_default/summary.html) template.
+
+For [single](layouts/_default/single.html) pages, the page content will be
+rendered inside an `<article>...</article>` block element.
+
+#### content-footer
+
+This block provides a footer for the page, which renders within the 
+`<footer></footer>` block at the end of the `<main></main>` section.
+
+Default content-footer definitions are not yet implemented.
+
+#### footer
+
+This block is for the site footer that appears at the end of every pages.
+
+The default footer block displays the [footer.html](layouts/partials/footer.html)
+partial.