From 441752d2d0d6c72ebf3d581e35f088668c21eb83 Mon Sep 17 00:00:00 2001
From: Joe Mooring <joe.mooring@veriphor.com>
Date: Sun, 19 Jan 2025 20:47:14 -0800
Subject: [PATCH] Refactor glossary lookup portion of link render hook

---
 content/en/contribute/documentation.md        | 91 +++++++++----------
 .../methods/page/AlternativeOutputFormats.md  |  2 +-
 content/en/methods/page/OutputFormats.md      |  2 +-
 layouts/_default/_markup/render-link.html     | 60 ++++++------
 layouts/shortcodes/gl.html                    | 46 ----------
 .../{gt.html => glossary-term.html}           |  4 +-
 6 files changed, 78 insertions(+), 127 deletions(-)
 delete mode 100644 layouts/shortcodes/gl.html
 rename layouts/shortcodes/{gt.html => glossary-term.html} (87%)

diff --git a/content/en/contribute/documentation.md b/content/en/contribute/documentation.md
index ac83a2307..8f24d8235 100644
--- a/content/en/contribute/documentation.md
+++ b/content/en/contribute/documentation.md
@@ -22,6 +22,12 @@ For documentation related to a new feature, please include the documentation cha
 
 ## Guidelines
 
+### Style
+
+Please adhere to Google's [developer documentation style guide].
+
+[developer documentation style guide]: https://developers.google.com/style
+
 ### Markdown
 
 Please follow these guidelines:
@@ -29,19 +35,41 @@ Please follow these guidelines:
 - Use [ATX] headings, not [setext] headings, levels 2 through 4
 - Use [fenced code blocks], not [indented code blocks]
 - Use hyphens, not asterisks, with unordered [list items]
-- Use the [note shortcode] instead of blockquotes
+- Use the [note shortcode] instead of blockquotes or bold text
 - Do not mix [raw HTML] within Markdown
 - Do not use bold text instead of a heading or description term (`dt`)
 - Remove consecutive blank lines (maximum of two)
 - Remove trailing spaces
 
-### Style
+### Glossary of terms
 
-Please adhere to Google's [developer documentation style guide].
+Each term in the glossary has its own dedicated page located within the `content/en/getting-started/glossary` directory. While these individual glossary pages are not published as standalone web pages during the build process, their content is included in other pages as needed.
 
-[developer documentation style guide]: https://developers.google.com/style
+To link to a term definition on the glossary page, use this custom link syntax:
 
-#### Terminology
+```text
+[term](g)
+```
+
+Lookups are case-insensitive, ignore formatting, and support both singular and plural forms. For example, all of these variations will link to the same glossary entry:
+
+```text
+[global resource](g)
+[Global Resource](g)
+[Global Resources](g)
+[`Global Resources`](g)
+```
+
+To insert a term definition, use the [`glossary-term`] shortcode:
+
+```text
+{{%/* glossary-term "global resource" */%}}
+```
+
+[glossary of terms]: /getting-started/glossary/
+[`glossary-term`]: #glossary-term
+
+### Terminology
 
 Please link to the [glossary of terms] when necessary, and use the terms consistently throughout the documentation. Of special note:
 
@@ -56,10 +84,7 @@ Please link to the [glossary of terms] when necessary, and use the terms consist
 
 Use the [glossary link] (`gl`) shortcode to insert a link to the glossary entry for the given term, and use the [glossary term] (`gt`) shortcode to insert the definition of the given term.
 
-[glossary link]: #glossary-link
-[glossary term]: #glossary-term
-
-#### Page titles and headings
+### Page titles and headings
 
 Please follow these guidelines for page titles and headings:
 
@@ -67,7 +92,7 @@ Please follow these guidelines for page titles and headings:
 - Avoid formatted strings in headings and page titles
 - Shorter is better
 
-#### Use active voice with present tense
+### Use active voice with present tense
 
 In software documentation, passive voice is unavoidable in some cases. Please use active voice when possible.
 
@@ -77,13 +102,13 @@ Yes → Build a static site with Hugo.
 No → This will cause Hugo to generate HTML files in the `public` directory.\
 Yes → Hugo generates HTML files in the `public` directory.
 
-#### Use second person instead of third person
+### Use second person instead of third person
 
 No → Users should exercise caution when deleting files.\
 Better → You must be cautious when deleting files.\
 Best → Be cautious when deleting files.
 
-#### Avoid adverbs when possible
+### Avoid adverbs when possible
 
 No → Hugo is extremely fast.\
 Yes → Hugo is fast.
@@ -92,13 +117,13 @@ Yes → Hugo is fast.
 "It's an adverb, Sam. It's a lazy tool of a weak mind." (Outbreak, 1995).
 {{% /note %}}
 
-#### Level 6 headings
+### Level 6 headings
 
 Level 6 headings are styled as `dt` elements. This was implemented to support a [glossary] with linkable terms.
 
 [glossary]: /getting-started/glossary/
 
-#### Function and method descriptions
+### Function and method descriptions
 
 When adding a page to the [functions] or [methods] section, begin the description with the word "Returns". With functions and methods that return a boolean value, begin the description with the phrase "Reports whether".
 
@@ -110,7 +135,7 @@ For example:
 [functions]: /functions
 [methods]: /methods
 
-#### Directory names, file names, and file paths
+### Directory names, file names, and file paths
 
 Enclose directory names, file names, and file paths within backticks, with the following exceptions:
 
@@ -119,7 +144,7 @@ Enclose directory names, file names, and file paths within backticks, with the f
 - Definition list terms
 - The description field in front matter
 
-#### Miscellaneous
+### Miscellaneous
 
 Other guidelines to consider:
 
@@ -321,41 +346,15 @@ This is a link to the [embedded alias template].
 
 [embedded alias template]: {{% eturl alias %}}
 
-### glossary link
+### glossary-term
 
-Use the glossary link (`gl`) shortcode to insert a link to the given glossary term.
+Use the `glossary-term` shortcode to insert the definition of the given glossary term.
 
 ```text
-{{%/* gl scalar */%}}
+{{%/* glossary-term scalar */%}}
 ```
 
-{{% gl scalar %}}
-
-Note that this site's link render hook provides a custom syntax to insert a link to the given glossary term. This method of linking to a glossary term is easier to both read and write:
-
-```text
-[scalar](g) <-- the g stands for glossary
-```
-
-[scalar](g)
-
-With both methods you can use either the singular or plural form of the term:
-
-```text
-{{%/* gl scalars */%}} and [scalars](g)
-```
-
-{{% gl scalars %}} and [scalars](g)
-
-### glossary term
-
-Use the glossary term (`gt`) shortcode to insert the definition of the given glossary term.
-
-```text
-{{%/* gt scalar */%}}
-```
-
-{{% gt scalar %}}
+{{% glossary-term scalar %}}
 
 ### include
 
diff --git a/content/en/methods/page/AlternativeOutputFormats.md b/content/en/methods/page/AlternativeOutputFormats.md
index c3b96b983..03e14e287 100644
--- a/content/en/methods/page/AlternativeOutputFormats.md
+++ b/content/en/methods/page/AlternativeOutputFormats.md
@@ -10,7 +10,7 @@ action:
   signatures: [PAGE.AlternativeOutputFormats]
 ---
 
-{{% gt "output format" %}}
+{{% glossary-term "output format" %}}
 
 The `AlternativeOutputFormats` method on a `Page` object returns a slice of `OutputFormat` objects, excluding the current output format, each representing one of the output formats enabled for the given page.. See&nbsp;[details](/templates/output-formats/).
 
diff --git a/content/en/methods/page/OutputFormats.md b/content/en/methods/page/OutputFormats.md
index 94831a163..a6d014a93 100644
--- a/content/en/methods/page/OutputFormats.md
+++ b/content/en/methods/page/OutputFormats.md
@@ -11,7 +11,7 @@ action:
 toc: true
 ---
 
-{{% gt "output format" %}}
+{{% glossary-term "output format" %}}
 
 The `OutputFormats` method on a `Page` object returns a slice of `OutputFormat` objects, each representing one of the output formats enabled for the given page. See&nbsp;[details](/templates/output-formats/).
 
diff --git a/layouts/_default/_markup/render-link.html b/layouts/_default/_markup/render-link.html
index c0663d39e..a0ee6b190 100644
--- a/layouts/_default/_markup/render-link.html
+++ b/layouts/_default/_markup/render-link.html
@@ -268,51 +268,49 @@ either of these shortcodes in conjunction with this render hook.
   {{- $contentPath := .contentPath }}
   {{- $errorLevel := .errorLevel }}
   {{- $renderHookName := .renderHookName }}
-  {{- $text := .text }}
+  {{- $text := .text | transform.Plainify | strings.ToLower }}
 
   {{- /* Initialize. */}}
-  {{- $basePath := "/getting-started/glossary" }}
+  {{- $glossaryPath := "/getting-started/glossary" }}
   {{- $termGiven := $text }}
   {{- $termActual := "" }}
   {{- $termSingular := inflect.Singularize $termGiven }}
 
-  {{- /* Validate the base path. */}}
-  {{- if not (site.GetPage $basePath) }}
-    {{- $msg := printf "The %q render hook was unable to find %s: see %s" $renderHookName $basePath $contentPath }}
-    {{- if eq $errorLevel "warning" }}
-      {{- warnf $msg }}
-    {{- else if eq $errorLevel "error" }}
-      {{- errorf $msg }}
+  {{- /* Verify that the glossary page exists. */}}
+  {{- $glossaryPage := site.GetPage $glossaryPath }}
+  {{- if not $glossaryPage }}
+    {{- errorf "The %q render hook was unable to find %s: see %s" $renderHookName $glossaryPath $contentPath }}
+  {{- end }}
+
+  {{- /* Theres a better way to handle this, but it works for now. */}}
+  {{- $cheating := dict
+    "chaining" "chain"
+    "localize" "localization"
+    "localized" "localization"
+    "paginating" "paginate"
+    "walking" "walk"
+  }}
+
+  {{- /* Verify that a glossary term page exists for the given term. */}}
+  {{- if site.GetPage (urls.JoinPath $glossaryPath ($termGiven | urlize)) }}
+    {{- $termActual = $termGiven }}
+  {{- else if site.GetPage (urls.JoinPath $glossaryPath ($termSingular | urlize)) }}
+    {{- $termActual = $termSingular }}
+  {{- else }}
+    {{- $termToTest := index $cheating $termGiven }}
+    {{- if site.GetPage (urls.JoinPath $glossaryPath ($termToTest | urlize)) }}
+      {{- $termActual = $termToTest }}
     {{- end }}
   {{- end }}
 
-  {{- /* Verify that a glossary term page exists for the given term. */}}
-  {{- if site.GetPage (urls.JoinPath $basePath ($termGiven | urlize)) }}
-    {{- $termActual = $termGiven }}
-  {{- else if site.GetPage (urls.JoinPath $basePath ($termSingular | urlize)) }}
-    {{- $termActual = $termSingular}}
-  {{- else }}
-    {{- $msg := printf "The %q render hook was unable to find a defintion for either the singular or plural form of the term %q: see %s" $renderHookName $termGiven $contentPath }}
-    {{- if eq $errorLevel "warning" }}
-      {{- warnf $msg }}
-    {{- else if eq $errorLevel "error" }}
-      {{- errorf $msg }}
-    {{- end }}
+  {{- if not $termActual }}
+    {{- errorf "The %q render hook was unable to find a glossary page for either the singular or plural form of the term %q: see %s" $renderHookName $termGiven $contentPath }}
   {{- end }}
 
   {{- /* Create the href attribute. */}}
   {{- $href := ""}}
   {{- if $termActual }}
-    {{- with site.GetPage $basePath }}
-      {{- $href = fmt.Printf "%s#%s" .RelPermalink (anchorize $termActual) }}
-    {{- else }}
-      {{- $msg := printf "The %q render hook was unable to find heading ID %q in %s. See %s" $renderHookName $basePath $contentPath }}
-      {{- if eq $errorLevel "warning" }}
-        {{- warnf $msg }}
-      {{- else if eq $errorLevel "error" }}
-        {{- errorf $msg }}
-      {{- end }}
-    {{- end }}
+    {{- $href = fmt.Printf "%s#%s" $glossaryPage.RelPermalink (anchorize $termActual) }}
   {{- end }}
 
   {{- return (dict "href" $href) }}
diff --git a/layouts/shortcodes/gl.html b/layouts/shortcodes/gl.html
deleted file mode 100644
index c1c2312a5..000000000
--- a/layouts/shortcodes/gl.html
+++ /dev/null
@@ -1,46 +0,0 @@
-{{- /*
-Renders a link to the glossary entry for the given term.
-
-It first checks for the existence of a glossary page for the given term. If no
-page is found, it then checks for a glossary page for the singular form of the
-term. If neither page exists, the shortcode raises an error.
-
-The rendered link displays the given term as the link text. However, the link
-itself does not point directly to the glossary term page. Instead, via its
-fragment, it points to an entry on the glossary page.
-
-@param {string} (.Get 0) The glossary term.
-@returns {template.HTML}
-
-@example {{% gl float %}}
-@example {{% gl "floating point" %}}
-*/}}
-
-{{- with $termGiven := .Get 0 }}
-  {{- $basePath := "/getting-started/glossary" }}
-  {{- $termActual := "" }}
-  {{- $termSingular := inflect.Singularize $termGiven }}
-
-  {{- with $gp :=site.GetPage $basePath }}
-
-    {{- /* Validate the given term using its singular and plural forms. */}}
-    {{- if site.GetPage (urls.JoinPath $basePath ($termGiven | urlize)) }}
-      {{- $termActual = $termGiven }}
-    {{- else if site.GetPage (urls.JoinPath $basePath ($termSingular | urlize)) }}
-      {{- $termActual = $termSingular}}
-    {{- else }}
-      {{- errorf "The glossary link (%s) shortcode was unable to find a defintion for either the singular or plural form of the term %q: see %s" $.Name $termGiven  $.Position }}
-    {{- end }}
-
-    {{- /* Render the link. */}}
-    {{- if $termActual }}
-      {{- $href := fmt.Printf "%s#%s" $gp.RelPermalink (anchorize $termActual) }}
-[{{ $termGiven }}]({{ $href }}){{/* Do not indent. */}}
-    {{- end }}
-
-  {{- else }}
-    {{- errorf "The glossary link (%s) shortcode was unable to find %s: see %s" $.Name $basePath $.Position }}
-  {{- end }}
-{{- else }}
-  {{- errorf "The glossary link (%s) shortcode requires one positional parameter: see %s" $.Name $.Position }}
-{{- end -}}
diff --git a/layouts/shortcodes/gt.html b/layouts/shortcodes/glossary-term.html
similarity index 87%
rename from layouts/shortcodes/gt.html
rename to layouts/shortcodes/glossary-term.html
index b7c85aa98..92ad93340 100644
--- a/layouts/shortcodes/gt.html
+++ b/layouts/shortcodes/glossary-term.html
@@ -4,8 +4,8 @@ Renders the definition of the given glossary term.
 @param {string} (.Get 0) The glossary term.
 @returns {template.HTML}
 
-@example {{% gt float %}}
-@example {{% gt "floating point" %}}
+@example {{% glossary-term float %}}
+@example {{% glossary-term "floating point" %}}
 */}}
 
 {{- with .Get 0 }}