Add more comments to explain the render pipeline

layouts/_partials/spec-content.html

@@ -3,9 +3,12 @@
   <h1>{{ .Title }}</h1>
   {{ with .Params.description }}<p class="page-description">{{ . | markdownify }}</p>{{ end }}
 
+  {{/*
+    Render an endpoints table of contents. This is the main difference
+    between our templates (which call the spec-content partial) and the default
+    Docsy template.
+  */}}
   {{ partial "endpoints-toc.html" . }}
 
   {{ .Content }}
-
-  {{ partial "page-meta-lastmod.html" . }}
-</div>
+</div>

layouts/_shortcodes/http-api.html

@@ -23,11 +23,18 @@
 {{ $api := .Params.api}}
 {{ $anchor_base := .Params.anchor_base}}
 
-{{/* Allow an outer page to collect endpoints (used for modules). */}}
+{{/*
+  
+  Figure out which Page object to pass to the `openapi/render-api` partial.
+  Either our own, or one stored under `endpoint_page` in the Scratch, if one
+  exists.
+
+*/}}
 {{ $target_page := .Page }}
 {{ with .Page.Scratch.Get "endpoint_page" }}
   {{ $target_page = . }}
 {{ end }}
+
 {{ $module_name := .Page.Scratch.Get "endpoint_module" }}
 
 {{ $api_data := index .Site.Data.api .Params.spec .Params.api }}

layouts/docs/list.html

@@ -1,14 +1,19 @@
 {{/*
 
-  A simplified version of the list.html partial in Docsy.
+  Override the `layouts/docs/list.html` template from Docsy. While this template
+  is equivalent to `single.html`, it's necessary to override both templates to
+  avoid falling back to the default Docsy templates.
+
+  https://gohugo.io/templates/types/#list
+
+  We use this list template to render the Client-Server API spec page and each
+  of its modules.
+
+  The contents of the "main" block below are inserted into the `./baseof.html`
+  base template.
 
 */}}
 
 {{ define "main" }}
-<div class="td-content">
-	<h1>{{ .Title }}</h1>
-        {{ with .Params.description }}<p class="page-description">{{ . | markdownify }}</p>{{ end }}
-        {{ partial "endpoints-toc.html" . }}
-	{{ .Content }}
-</div>
+  {{ partial "spec-content.html" . }}
 {{ end }}

layouts/docs/single.html

@@ -1,3 +1,19 @@
+{{/*
+
+  Override the `layouts/docs/single.html` template from Docsy. While this template
+  is equivalent to `list.html`, it's necessary to override both templates to
+  avoid falling back to the default Docsy templates.
+
+  https://gohugo.io/templates/types/#single
+
+  We use this single template to render the all API spec pages *except* the
+  Client-Server API. The Client-Server API spec page contains modules, and thus
+  is handled separately.
+
+  The contents of the "main" block below are inserted into the `./baseof.html`
+  base template.
+
+*/}}
 {{ define "main" }}
   {{ partial "spec-content.html" . }}
-{{ end }}
+{{ end }}