Improve comments

4 files changed, 26 insertions, 24 deletions

diff --git a/README.md b/README.md
index 9346dc3..a9e3577 100644
--- a/README.md
+++ b/README.md
@@ -58,19 +58,19 @@ Configuration options may be copied and modified from the theme defaults:
 
 ```yaml
 params:
-  color: teal  # Any color in CSS syntax
-  width: 42rem  # Any length in CSS syntax
-  footer: Except where otherwise noted, content on this site is licensed under
+  color: teal           # Any color in CSS syntax
+  width: 42rem          # Any length in CSS syntax
+  footer: Except where otherwise noted, content on this site is licensed under a
     a <a href="http://creativecommons.org/licenses/by/4.0/" rel="license">
     Creative Commons Attribution 4.0 International License</a>.
   rss: To subscribe to this RSS feed, copy its address and paste it into your
     favorite feed reader.
-  summaries: false
-  schema: false
-  opengraph: false
-  twittercards: false
+  summaries: false      # Set to true to show summaries of posts on homepage
+  schema: false         # Set to true to add Schema.org metadata
+  opengraph: false      # Set to true to add Open Graph metadata
+  twittercards: false   # Set to true to add Twitter Cards metadata
   utterances:
-    enabled: false
+    enabled: false      # Set to true to add Utterances comments to single posts
     repo:
     issueterm: pathname
     theme: github-light
diff --git a/config.yaml b/config.yaml
index 9171d11..bf3f836 100644
--- a/config.yaml
+++ b/config.yaml
@@ -1,17 +1,17 @@
 params:
-  color: teal  # Any color in CSS syntax
-  width: 42rem  # Any length in CSS syntax
-  footer: Except where otherwise noted, content on this site is licensed under
+  color: teal           # Any color in CSS syntax
+  width: 42rem          # Any length in CSS syntax
+  footer: Except where otherwise noted, content on this site is licensed under a
     a <a href="http://creativecommons.org/licenses/by/4.0/" rel="license">
     Creative Commons Attribution 4.0 International License</a>.
   rss: To subscribe to this RSS feed, copy its address and paste it into your
     favorite feed reader.
-  summaries: false
-  schema: false
-  opengraph: false
-  twittercards: false
+  summaries: false      # Set to true to show summaries of posts on homepage
+  schema: false         # Set to true to add Schema.org metadata
+  opengraph: false      # Set to true to add Open Graph metadata
+  twittercards: false   # Set to true to add Twitter Cards metadata
   utterances:
-    enabled: false
+    enabled: false      # Set to true to add Utterances comments to single posts
     repo:
     issueterm: pathname
     theme: github-light
diff --git a/layouts/_default/baseof.html b/layouts/_default/baseof.html
index a767cc6..41f99b8 100644
--- a/layouts/_default/baseof.html
+++ b/layouts/_default/baseof.html
@@ -20,10 +20,10 @@
   {{ end }}
   {{ resources.Get "css/base.temp.css" | resources.ExecuteAsTemplate "css/base.css" . | minify | fingerprint | .Page.Scratch.SetInMap "css" "base" }}
   {{/*
-    In the following block, Hugo is forced to stop and pre-render the
-    content of the current page with all its shortcodes. Thanks to this
-    pre-render, shortcodes can be used to load additional CSS and JS
-    resources through the .Scratch variable.
+    In this block Hugo is forced to load the page's content, effectively
+    pre-rendering all its shortcodes. Thanks to this pre-render,
+    shortcodes can load additional CSS and JS resources by adding them
+    to the "css" and "js" entries of the global .Scratch variable.
   */}}
   {{ block "loadshortcodes" . }}{{ with .Content }}{{ end }}{{ end }}
   {{ range .Scratch.GetSortedMapValues "css" }}
diff --git a/layouts/index.html b/layouts/index.html
index d98a981..af8e2c2 100644
--- a/layouts/index.html
+++ b/layouts/index.html
@@ -2,10 +2,12 @@
 
 {{/*
   Here Hugo is forced to cycle through all the items that will appear on
-  the page, and pre-render their contents with all their shortcodes. If
-  these shortcodes are used to load additional CSS and JS resources,
-  these resources are then transferred from their local .Scratch
-  variables to the globally available .Scratch variable.
+  the page, effectively pre-rendering all their shortcodes. Afterwards,
+  when a shortcode contains a "css" or a "js" entry in their local
+  .Scratch variable, the content of this entry is merged to the content
+  of the corresponding entry in the global .Scratch variable. These
+  resources are then loaded in the head of the page from the global
+  .Scratch variable (see layout baseof.html).
 */}}
 {{ $paginator := where site.RegularPages "Type" "in" site.Params.mainSections | .Paginate }}
 {{ range $paginator.Pages }}