Rework introduction to templating

jmooring · web-flow · commit c4611eab5261 · 2024-03-08T19:26:17.000-08:00
diff --git a/.cspell.json b/.cspell.json
@@ -20,13 +20,11 @@
   ],
   "ignoreRegExpList": [
     "# cspell: ignore fenced code blocks",
-    "^(\\s*`{3,}).*[\\s\\S]*?^\\1",
+    "^(\\s*`{3,}).*[\\s\\S]*?^\\1$",
     "# cspell: ignore words joined with dot",
     "\\w+\\.\\w+",
     "# cspell: ignore strings within backticks",
     "`.+`",
-    "# cspell: ignore strings within single quotes",
-    "'.+'",
     "# cspell: ignore strings within double quotes",
     "\".+\"",
     "# cspell: ignore strings within brackets",
diff --git a/content/en/about/hugo-and-gdpr.md b/content/en/about/hugo-and-gdpr.md
@@ -22,7 +22,7 @@ aliases: [/privacy/,/gdpr/]
  Note that:
 
  * These settings have their defaults setting set to _off_, i.e. how it worked before Hugo `0.41`. You must do your own evaluation of your site and apply the appropriate settings.
- * These settings work with the [internal templates](/templates/internal/). Some theme may contain custom templates for embedding services like Google Analytics. In that case these options have no effect.
+ * These settings work with the [embedded templates](/templates/embedded/). Some theme may contain custom templates for embedding services like Google Analytics. In that case these options have no effect.
  * We will continue this work and improve this further in future Hugo versions.
 
 ## All privacy settings
diff --git a/content/en/content-management/comments.md b/content/en/content-management/comments.md
@@ -37,7 +37,7 @@ For many websites, this is enough configuration. However, you also have the opti
 
 ### Render Hugo's built-in Disqus partial template
 
-Disqus has its own [internal template](/templates/internal/#disqus) available, to render it add the following code where you want comments to appear:
+Disqus has its own [internal template](/templates/embedded/#disqus) available, to render it add the following code where you want comments to appear:
 
 ```go-html-template
 {{ template "_internal/disqus.html" . }}
@@ -66,7 +66,7 @@ Open-source commenting systems:
 - [Utterances](https://utteranc.es/)
 
 [configuration]: /getting-started/configuration/
-[disquspartial]: /templates/internal/#disqus
+[disquspartial]: /templates/embedded/#disqus
 [disqussetup]: https://disqus.com/profile/signup/
 [forum]: https://discourse.gohugo.io
 [front matter]: /content-management/front-matter/
diff --git a/content/en/content-management/toc.md b/content/en/content-management/toc.md
@@ -110,7 +110,7 @@ A collection of textile samples lay spread out on the table - Samsa was a travel
 
 Hugo will take this AsciiDoc and create a table of contents store it in the page variable `.TableOfContents`, in the same as described for Markdown.
 
-[conditionals]: /templates/introduction/#conditionals
+[conditionals]: /templates/introduction/#conditional-blocks
 [front matter]: /content-management/front-matter/
 [pagevars]: /methods/page/
 [partials]: /templates/partials/
diff --git a/content/en/functions/collections/Where.md b/content/en/functions/collections/Where.md
@@ -243,7 +243,7 @@ To return a collection of future events:
 {{ $futureEvents := where $events "Params.eventDate" "gt" now }}
 ```
 
-When working with YAML or JSON, or quoted TOML values, custom dates are strings; you cannot compare them with `time.Time` values. String comparisons may be possible if the custom date layout is consistent from one page to the next. However, to be safe, filter the pages by ranging through the collection:
+When working with YAML or JSON, or quoted TOML values, custom dates are strings; you cannot compare them with `time.Time` values. String comparisons may be possible if the custom date layout is consistent from one page to the next. To be safe, filter the pages by ranging through the collection:
 
 ```go-html-template
 {{ $events := where .Site.RegularPages "Type" "events" }}
diff --git a/content/en/functions/go-template/template.md b/content/en/functions/go-template/template.md
@@ -13,7 +13,7 @@ action:
   signatures: ['template NAME [CONTEXT]']
 ---
 
-Use the `template` function to execute [internal templates]. For example:
+Use the `template` function to execute [embedded templates]. For example:
 
 ```go-html-template
 {{ range (.Paginate .Pages).Pages }}
@@ -46,4 +46,4 @@ The example above can be rewritten using an [inline partial] template:
 
 [`partial`]: /functions/partials/include/
 [inline partial]: /templates/partials/#inline-partials
-[internal templates]: /templates/internal/
+[embedded templates]: /templates/embedded/
diff --git a/content/en/functions/resources/FromString.md b/content/en/functions/resources/FromString.md
@@ -37,7 +37,7 @@ Place this in your baseof.html template:
   {{ $m := dict
     "hugo_version" hugo.Version
     "build_date" (now.Format $rfc3339)
-    "last_modified" (site.LastChange.Format $rfc3339)
+    "last_modified" (site.Lastmod.Format $rfc3339)
   }}
   {{ $json := jsonify $m }}
   {{ $r := resources.FromString "site.json" $json }}
@@ -61,7 +61,7 @@ Combine `resources.FromString` with [`resources.ExecuteAsTemplate`] if your stri
     {{ $m := dict
       "hugo_version" hugo.Version
       "build_date" (now.Format $rfc3339)
-      "last_modified" (site.LastChange.Format $rfc3339)
+      "last_modified" (site.Lastmod.Format $rfc3339)
     }}
     {{ $json := jsonify $m }}
     `
diff --git a/content/en/functions/strings/ContainsNonSpace.md b/content/en/functions/strings/ContainsNonSpace.md
@@ -1,6 +1,6 @@
 ---
 title: strings.ContainsNonSpace
-description: Reports whether the given string contains any non-space characters as defined by Unicode’s White Space property.
+description: Reports whether the given string contains any non-space characters as defined by Unicode's White Space property.
 categories: []
 keywords: []
 action:
@@ -24,7 +24,7 @@ aliases: [/functions/strings.containsnonspace]
 {{ strings.ContainsNonSpace "\n abc" }} → true
 ```
 
-Common white space characters include:
+Common whitespace characters include:
 
 ```text
 '\t', '\n', '\v', '\f', '\r', ' '
diff --git a/content/en/getting-started/glossary.md b/content/en/getting-started/glossary.md
@@ -98,7 +98,7 @@ A template called with the `.Page.Render` method. See&nbsp;[details](/templates/
 
 ###### context
 
-Represented by a dot "." within a [template action](#template-action), context is the current location in a data structure. For example, while iterating over a [collection](#collection) of pages, the context within each iteration is the page's data structure. The context received by each template depends on template type and/or how it was called. See&nbsp;[details](/templates/introduction/#the-dot).
+Represented by a dot "." within a [template action](#template-action), context is the current location in a data structure. For example, while iterating over a [collection](#collection) of pages, the context within each iteration is the page's data structure. The context received by each template depends on template type and/or how it was called. See&nbsp;[details](/templates/introduction/#context).
 
 ###### default sort order
 
@@ -363,6 +363,14 @@ A numbered sequence of elements. Unlike Go's [array](#array) data type, slices a
 
 A sequence of bytes. For example, `"What is 6 times 7?"`&nbsp;.
 
+###### string literal (interpreted)
+
+Interpreted string literals are character sequences between double quotes, as in "foo". Within the quotes, any character may appear except a newline and an unescaped double quote. The text between the quotes forms the value of the literal, with backslash escapes interpreted. See [details](https://go.dev/ref/spec#String_literals).
+
+###### string literal (raw)
+
+Raw string literals are character sequences between backticks, as in \`bar\`. Within the backticks, any character may appear except a backtick. Backslashes have no special meaning and the string may contain newlines. Carriage return characters ('\r') inside raw string literals are discarded from the raw string value. See [details](https://go.dev/ref/spec#String_literals).
+
 ###### taxonomic weight
 
 Defined in front matter and unique to each taxonomy, this [weight](#weight) determines the sort order of page collections contained within a [taxonomy object](#taxonomy-object). See&nbsp;[details](/templates/taxonomy-templates/#assign-weight).
diff --git a/content/en/methods/page/Path.md b/content/en/methods/page/Path.md
@@ -108,7 +108,7 @@ Methods|Functions|Shortcodes
 [`Shortcode.Ref`]||
 [`Shortcode.RelRef`]||
 
-[`urls.Ref`]: functions/urls/ref/
+[`urls.Ref`]: /functions/urls/ref/
 [`urls.RelRef`]: /functions/urls/relref/
 [`Page.GetPage`]: /methods/page/getpage/
 [`Site.GetPage`]: /methods/site/getpage/
diff --git a/content/en/methods/page/PlainWords.md b/content/en/methods/page/PlainWords.md
@@ -15,7 +15,7 @@ action:
 The `PlainWords` method on a `Page` object calls the [`Plain`] method, then uses Go's [`strings.Fields`] function to split the result into words.
 
 {{% note %}}
-_Fields splits the string s around each instance of one or more consecutive white space characters, as defined by [`unicode.IsSpace`], returning a slice of substrings of s or an empty slice if s contains only white space._
+_Fields splits the string s around each instance of one or more consecutive whitespace characters, as defined by [`unicode.IsSpace`], returning a slice of substrings of s or an empty slice if s contains only whitespace._
 
 [`unicode.IsSpace`]: https://pkg.go.dev/unicode#IsSpace
 {{% /note %}}
diff --git a/content/en/methods/site/Params.md b/content/en/methods/site/Params.md
@@ -33,7 +33,7 @@ Access the custom parameters by [chaining] the [identifiers]:
 {{ .Site.Params.author.name }} → John Smith
 
 {{ $layout := .Site.Params.layouts.rfc_1123 }}
-{{ .Site.LastChange.Format $layout }} → Tue, 17 Oct 2023 13:21:02 PDT
+{{ .Site.Lastmod.Format $layout }} → Tue, 17 Oct 2023 13:21:02 PDT
 ```
 
 In the template example above, each of the keys is a valid identifier. For example, none of the keys contains a hyphen. To access a key that is not a valid identifier, use the [`index`] function:
diff --git a/content/en/render-hooks/images.md b/content/en/render-hooks/images.md
@@ -72,7 +72,7 @@ block = true
 ## Examples
 
 {{% note %}}
-With inline elements such as images and links, remove leading and trailing white space using the `{{‑ ‑}}` delimiter notation to prevent white space between adjacent inline elements and text.
+With inline elements such as images and links, remove leading and trailing whitespace using the `{{‑ ‑}}` delimiter notation to prevent whitespace between adjacent inline elements and text.
 {{% /note %}}
 
 In its default configuration, Hugo renders Markdown images according to the [CommonMark specification]. To create a render hook that does the same thing:
diff --git a/content/en/render-hooks/links.md b/content/en/render-hooks/links.md
@@ -55,7 +55,7 @@ Link render hook templates receive the following context:
 ## Examples
 
 {{% note %}}
-With inline elements such as images and links, remove leading and trailing white space using the `{{‑ ‑}}` delimiter notation to prevent white space between adjacent inline elements and text.
+With inline elements such as images and links, remove leading and trailing whitespace using the `{{‑ ‑}}` delimiter notation to prevent whitespace between adjacent inline elements and text.
 {{% /note %}}
 
 In its default configuration, Hugo renders Markdown links according to the [CommonMark specification]. To create a render hook that does the same thing:
diff --git a/content/en/templates/embedded.md b/content/en/templates/embedded.md
@@ -1,6 +1,6 @@
 ---
-title: Internal templates
-description: Hugo ships with a group of boilerplate templates that cover the most common use cases for static websites.
+title: Embedded templates
+description: Hugo provides embedded templates for common use cases.
 categories: [templates]
 keywords: [internal, analytics,]
 menu:
@@ -9,12 +9,9 @@ menu:
     weight: 190
 weight: 190
 toc: true
+aliases: [/templates/internal]
 ---
 
-{{% note %}}
-While the following internal templates are called similar to partials, they do *not* observe the partial template lookup order.
-{{% /note %}}
-
 ## Disqus
 
 {{% note %}}
@@ -26,7 +23,16 @@ To override Hugo's embedded Disqus template, copy the [source code] to a file wi
 [source code]: {{% eturl disqus %}}
 {{% /note %}}
 
-Hugo includes an embedded template for [Disqus comments][disqus], a popular commenting system for both static and dynamic websites. To effectively use Disqus, secure a Disqus "shortname" by [signing up for the free service][disqussignup].
+Hugo includes an embedded template for [Disqus], a popular commenting system for both static and dynamic websites. To effectively use Disqus, secure a Disqus "shortname" by [signing up] for the free service.
+
+[Disqus]: https://disqus.com
+[signing up]: https://disqus.com/profile/signup/
+
+To include the embedded template:
+
+```go-html-template
+{{ template "_internal/disqus.html" . }}
+```
 
 ### Configure Disqus
 
@@ -45,17 +51,9 @@ Hugo's Disqus template accesses this value with:
 
 You can also set the following in the front matter for a given piece of content:
 
-* `disqus_identifier`
-* `disqus_title`
-* `disqus_url`
-
-### Use the Disqus template
-
-To add Disqus, include the following line in the templates where you want your comments to appear:
-
-```go-html-template
-{{ template "_internal/disqus.html" . }}
-```
+- `disqus_identifier`
+- `disqus_title`
+- `disqus_url`
 
 ### Conditional loading of Disqus comments
 
@@ -106,6 +104,12 @@ Hugo includes an embedded template supporting [Google Analytics 4].
 
 [Google Analytics 4]: https://support.google.com/analytics/answer/10089681
 
+To include the embedded template:
+
+```go-html-template
+{{ template "_internal/google_analytics.html" . }}
+```
+
 ### Configure Google Analytics
 
 Provide your tracking ID in your configuration file:
@@ -116,15 +120,7 @@ Provide your tracking ID in your configuration file:
 ID = "G-MEASUREMENT_ID"
 {{</ code-toggle >}}
 
-### Use the Google Analytics template
-
-Include the Google Analytics internal template in your templates where you want the code to appear:
-
-```go-html-template
-{{ template "_internal/google_analytics.html" . }}
-```
-
-To create your own template, access the configured ID with `{{ site.Config.Services.GoogleAnalytics.ID }}`.
+To use this value in your own template, access the configured ID with `{{ site.Config.Services.GoogleAnalytics.ID }}`.
 
 ## Open Graph
 
@@ -140,6 +136,12 @@ To override Hugo's embedded Open Graph template, copy the [source code] to a fil
 Hugo includes an embedded template for the [Open Graph protocol](https://ogp.me/), metadata that enables a page to become a rich object in a social graph.
 This format is used for Facebook and some other sites.
 
+To include the embedded template:
+
+```go-html-template
+{{ template "_internal/opengraph.html" . }}
+```
+
 ### Configure Open Graph
 
 Hugo's Open Graph template is configured using a mix of configuration variables and [front-matter](/content-management/front-matter/) on individual pages.
@@ -177,14 +179,6 @@ Various optional metadata can also be set:
 
 If using YouTube this will produce a og:video tag like `<meta property="og:video" content="url">`. Use the `https://youtu.be/<id>` format with YouTube videos (example: `https://youtu.be/qtIqKaDlqXo`).
 
-### Use the Open Graph template
-
-To add Open Graph metadata, include the following line between the `<head>` tags in your templates:
-
-```go-html-template
-{{ template "_internal/opengraph.html" . }}
-```
-
 ## Schema
 
 {{% note %}}
@@ -200,10 +194,10 @@ Hugo includes an embedded template to render [microdata] `meta` elements within
 
 [microdata]: https://html.spec.whatwg.org/multipage/microdata.html#microdata
 
-To call the embedded template from your templates:
+To include the embedded template:
 
 ```go-html-template
-{{ template "_internal/schema.xml" . }}
+{{ template "_internal/schema.html" . }}
 ```
 
 ## Twitter Cards
@@ -220,6 +214,12 @@ To override Hugo's embedded Twitter Cards template, copy the [source code] to a
 Hugo includes an embedded template for [Twitter Cards](https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/abouts-cards),
 metadata used to attach rich media to Tweets linking to your site.
 
+To include the embedded template:
+
+```go-html-template
+{{ template "_internal/twitter_cards.html" . }}
+```
+
 ### Configure Twitter Cards
 
 Hugo's Twitter Card template is configured using a mix of configuration variables and [front-matter](/content-management/front-matter/) on individual pages.
@@ -254,16 +254,3 @@ NOTE: The `@` will be added for you
 ```html
 <meta name="twitter:site" content="@GoHugoIO"/>
 ```
-
-### Use the Twitter Cards template
-
-To add Twitter card metadata, include the following line immediately after the `<head>` element in your templates:
-
-```go-html-template
-{{ template "_internal/twitter_cards.html" . }}
-```
-
-
-
-[disqus]: https://disqus.com
-[disqussignup]: https://disqus.com/profile/signup/
diff --git a/content/en/templates/introduction.md b/content/en/templates/introduction.md
diff --git a/content/en/templates/shortcode-templates.md b/content/en/templates/shortcode-templates.md
