Improve glossary

archetypes/glossary.md

@@ -1,19 +1,12 @@
 ---
 title: {{ replace .File.ContentBaseName "-" " " }}
+reference: 
 ---
 
 <!--
-You can insert these definitions in other pages using the `glossary-term` shortcode, so they must be self-contained.
+Glossary terms are maintained on dedicated individual pages within the documentation. These pages act as a central repository for all term definitions, although they are not directly visible to site visitors.
 
-Do this:
+Definitions must be presented in complete sentences, with the first sentence always explicitly introducing the term being defined. The first occurrence of the term itself, along with any other referenced glossary terms, should be presented in italics within the definition. However, when a term is an alias for another term, the definition can simply state "See [page kind]" (e.g., "See [page kind]"). These guidelines aim to enhance the readability and consistency of all glossary definitions.
 
-    A _foo_ is big bar.
-    
-Not this:
-
-    A big bar.
-    
-Italicize the term whenever you use it in the definition.
-
-An exception to this rule occurs when a term is an alias for another. In such cases, it is sufficient to use the phrase 'See [page kind]'."
+The "reference" field in the front matter of each definition page should be used to include a "See details" link at the end of the definition. This allows for flexible placement of the definition within the documentation while maintaining a central source for the definition itself. The value in the "reference" field must correspond to the logical path of the relevant page within the documentation structure.
 -->

content/en/content-management/archetypes.md

@@ -76,13 +76,13 @@ Date
 : (`string`) The current date and time, formatted in compliance with RFC3339.
 
 File
-: (`hugolib.fileInfo`) Returns file information for the current page. See [details](/methods/page/file).
+: (`hugolib.fileInfo`) Returns file information for the current page. See [details](/methods/page/file).
 
 Type
 : (`string`) The [content type](g) inferred from the top-level directory name, or as specified by the `--kind` flag passed to the `hugo new content` command.
 
 Site
-: (`page.Site`) The current site object. See [details](/methods/site/).
+: (`page.Site`) The current site object. See [details](/methods/site/).
 
 ## Date format
 

content/en/content-management/formats.md

@@ -74,7 +74,7 @@ Create your content in [HTML] preceded by front matter. The content is typically
 
 ### Emacs Org Mode
 
-Create your content in the [Emacs Org Mode] format preceded by front matter. You can use Org Mode keywords for front matter. See [details].
+Create your content in the [Emacs Org Mode] format preceded by front matter. You can use Org Mode keywords for front matter. See [details].
 
 [details]: /content-management/front-matter/#emacs-org-mode
 [Emacs Org Mode]: https://orgmode.org/

content/en/content-management/image-processing/index.md

@@ -17,7 +17,7 @@ To process an image you must access the file as a page resource, global resource
 
 ### Page resource
 
-A page resource is a file within a [page bundle]. A page bundle is a directory with an `index.md` or `_index.md` file at its root.
+A page resource is a file within a [page bundle]. A page bundle is a directory with an `index.md` or `_index.md` file at its root.
 
 ```text
 content/

content/en/content-management/page-bundles.md

@@ -30,10 +30,10 @@ The "about" page is a page bundle. It logically associates a resource with conte
 Page bundles are either _leaf bundles_ or _branch bundles_.
 
 leaf bundle
-: A _leaf bundle_ is a directory that contains an `index.md` file and zero or more resources. Analogous to a physical leaf, a leaf bundle is at the end of a branch. It has no descendants.
+: A _leaf bundle_ is a directory that contains an `index.md` file and zero or more resources. Analogous to a physical leaf, a leaf bundle is at the end of a branch. It has no descendants.
 
 branch bundle
-: A _branch bundle_ is a directory that contains an `_index.md` file and zero or more resources. Analogous to a physical branch, a branch bundle may have descendants including leaf bundles and other branch bundles. Top level directories with or without `_index.md` files are also branch bundles. This includes the home page.
+: A _branch bundle_ is a directory that contains an `_index.md` file and zero or more resources. Analogous to a physical branch, a branch bundle may have descendants including leaf bundles and other branch bundles. Top level directories with or without `_index.md` files are also branch bundles. This includes the home page.
 
 {{% note %}}
 In the definitions above and the examples below, the extension of the index file depends on the [content format](g). For example, use `index.md` for Markdown content, `index.html` for HTML content, `index.adoc` for AsciiDoc content, etc.
@@ -63,7 +63,7 @@ Files with [resource type](g) `page` include content written in Markdown, HTML,
 
 ## Leaf bundles
 
-A _leaf bundle_ is a directory that contains an `index.md` file and zero or more resources. Analogous to a physical leaf, a leaf bundle is at the end of a branch. It has no descendants.
+A _leaf bundle_ is a directory that contains an `index.md` file and zero or more resources. Analogous to a physical leaf, a leaf bundle is at the end of a branch. It has no descendants.
 
 ```text
 content/
@@ -114,7 +114,7 @@ Create leaf bundles at any depth within the `content` directory, but a leaf bund
 
 ## Branch bundles
 
-A _branch bundle_ is a directory that contains an `_index.md` file and zero or more resources. Analogous to a physical branch, a branch bundle may have descendants including leaf bundles and other branch bundles. Top level directories with or without `_index.md` files are also branch bundles. This includes the home page.
+A _branch bundle_ is a directory that contains an `_index.md` file and zero or more resources. Analogous to a physical branch, a branch bundle may have descendants including leaf bundles and other branch bundles. Top level directories with or without `_index.md` files are also branch bundles. This includes the home page.
 
 ```text
 content/

content/en/content-management/page-resources.md

@@ -12,7 +12,7 @@ toc: true
 ---
 
 Page resources are only accessible from [page bundles](/content-management/page-bundles), those directories with `index.md` or
-`_index.md` files at their root. Page resources are only available to the
+`_index.md` files at their root. Page resources are only available to the
 page with which they are bundled.
 
 In this example, `first-post` is a page bundle with access to 10 page resources including audio, data, documents, images, and video. Although `second-post` is also a page bundle, it has no page resources and is unable to directly access the page resources associated with `first-post`.

content/en/content-management/sections.md

@@ -15,10 +15,10 @@ aliases: [/content/sections/]
 
 ## Overview
 
-A section is a top-level content directory, or any content directory with an `_index.md` file. A content directory with an `_index.md` file is also known as a [branch bundle](g). Section templates receive one or more page [collections](g) in [context](g).
+A section is a top-level content directory, or any content directory with an `_index.md` file. A content directory with an `_index.md` file is also known as a [branch bundle](g). Section templates receive one or more page [collections](g) in [context](g).
 
 {{% note %}}
-Although top-level directories without `_index.md` files are sections, we recommend creating `_index.md` files in _all_ sections.
+Although top-level directories without `_index.md` files are sections, we recommend creating `_index.md` files in _all_ sections.
 {{% /note %}}
 
 A typical site consists of one or more sections. For example:

content/en/contribute/documentation.md

@@ -43,7 +43,9 @@ Please follow these guidelines:
 
 ### Glossary of terms
 
-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.
+Glossary terms are maintained on individual pages. While not directly accessible to site visitors, these pages act as a central repository for term definitions.
+
+Definitions must be presented in complete sentences, with the first sentence always introducing the term being defined. To enhance readability and consistency, the first occurrence of the term and any other referenced glossary terms should be italicized.
 
 To link to a term definition on the glossary page, use this custom link syntax:
 

content/en/getting-started/configuration.md

@@ -228,13 +228,13 @@ See [Configure File Caches](#configure-file-caches).
 
 ###### canonifyURLs
 
-(`bool`) See [details](/content-management/urls/#canonical-urls) before enabling this feature. Default is `false`.
+(`bool`) See [details](/content-management/urls/#canonical-urls) before enabling this feature. Default is `false`.
 
 ###### capitalizeListTitles
 
 {{< new-in 0.123.3 >}}
 
-(`bool`) Whether to capitalize automatic list titles. Applicable to section, taxonomy, and term pages. Default is `true`. You can change the capitalization style in your site configuration to one of `ap`, `chicago`, `go`, `firstupper`, or `none`. See [details].
+(`bool`) Whether to capitalize automatic list titles. Applicable to section, taxonomy, and term pages. Default is `true`. You can change the capitalization style in your site configuration to one of `ap`, `chicago`, `go`, `firstupper`, or `none`. See&nbsp;[details].
 
 [details]: /getting-started/configuration/#configure-title-case
 
@@ -460,7 +460,7 @@ See [Related Content](/content-management/related/#configure-related-content).
 
 ###### relativeURLs
 
-(`bool`) See [details](/content-management/urls/#relative-urls) before enabling this feature. Default is `false`.
+(`bool`) See&nbsp;[details](/content-management/urls/#relative-urls) before enabling this feature. Default is `false`.
 
 ###### removePathAccents
 
@@ -541,7 +541,7 @@ See [module configuration](/hugo-modules/configuration/#module-configuration-imp
 
 ###### uglyURLs
 
-(`bool` or `map`) Whether to generate uglyURLs. Default is `false`. See [details](/content-management/urls/#appearance).
+(`bool` or `map`) Whether to generate uglyURLs. Default is `false`. See&nbsp;[details](/content-management/urls/#appearance).
 
 ###### watch
 

content/en/getting-started/glossary/archetype.md

@@ -1,5 +1,6 @@
 ---
 title: archetype
+details: /content-management/archetypes
 ---
 
-An archetype is a template for new content. See [details](/content-management/archetypes/).
+An _archetype_ is a template for new content.

content/en/getting-started/glossary/argument.md

@@ -2,4 +2,4 @@
 title: argument
 ---
 
-A [scalar](g), [array](g), [slice](g), [map](g), or [object](g) passed to a [function](g), [method](g), or [shortcode](g).
+An _argument_ is a [_scalar_](g), [_array_](g), [_slice_](g), [_map_](g), or [_object_](g) passed to a [_function_](g), [_method_](g), or [_shortcode_](g).

content/en/getting-started/glossary/array.md

@@ -2,4 +2,4 @@
 title: array
 ---
 
-A numbered sequence of [elements](g). Unlike Go's [slice](g) data type, an array has a fixed length. Elements within an array can be [scalars](g), slices, [maps](g), pages, or other arrays. See the [Go documentation](https://go.dev/ref/spec#Array_types) for details.
+An _array_ is a numbered sequence of [_elements_](g). Unlike Go's [_slice_](g) data type, an array has a fixed length. Elements within an array can be [_scalars_](g), slices, [_maps_](g), pages, or other arrays.

content/en/getting-started/glossary/boolean.md

@@ -2,4 +2,4 @@
 title: boolean
 ---
 
-A data type with two possible values, either `true` or `false`.
+A _boolean_ is a data type with two possible values, either `true` or `false`.

content/en/getting-started/glossary/branch-bundle.md

@@ -1,5 +1,6 @@
 ---
 title: branch bundle
+reference: /content-management/page-bundles
 ---
 
-A directory that contains an `_index.md` file and zero or more [resources](g). Analogous to a physical branch, a branch bundle may have descendants including leaf bundles and other branch bundles. Top level directories with or without `_index.md` files are also branch bundles. This includes the home page. See [details](/content-management/page-bundles/).
+A _branch bundle_ is a top-level content directory or any content directory containing an `_index.md` file. Analogous to a physical branch, a branch bundle may have descendants including [_leaf bundles_](g) and other branch bundles. A branch bundle may also contain [_page resources_](g) such as images.

content/en/getting-started/glossary/build.md

@@ -2,4 +2,4 @@
 title: build
 ---
 
-To generate a static site that includes HTML files and assets such as images, CSS, and JavaScript. The build process includes rendering and resource transformations.
+To _build_ a site is to generate HTML files and assets such as images, CSS files, and JavaScript files. The build process includes rendering and resource transformations.

content/en/getting-started/glossary/cjk.md

@@ -2,4 +2,4 @@
 title: CJK
 ---
 
-A collective term for the Chinese, Japanese, and Korean languages. See [details](https://en.wikipedia.org/wiki/CJK_characters).
+A collective term for the Chinese, Japanese, and Korean languages.

content/en/getting-started/glossary/content-adapter.md

@@ -1,5 +1,6 @@
 ---
 title: content adapter
+reference: /content-management/content-adapters
 ---
 
-A template that dynamically creates pages when building a site. For example, use a content adapter to create pages from a remote data source such as JSON, TOML, YAML, or XML. See [details](/content-management/content-adapters/).
+A template that dynamically creates pages when building a site. For example, use a content adapter to create pages from a remote data source such as JSON, TOML, YAML, or XML.

content/en/getting-started/glossary/content-format.md

@@ -1,5 +1,6 @@
 ---
 title: content format
+reference: /content-management/formats
 ---
 
-A markup language for creating content. Typically Markdown, but may also be HTML, AsciiDoc, Org, Pandoc, or reStructuredText. See [details](/content-management/formats/).
+A markup language for creating content. Typically Markdown, but may also be HTML, AsciiDoc, Org, Pandoc, or reStructuredText.

content/en/getting-started/glossary/content-type.md

@@ -1,5 +1,6 @@
 ---
 title: content type
+reference: /content-management/types
 ---
 
-A classification of content inferred from the top-level directory name or the `type` set in [front matter](g). Pages in the root of the `content` directory, including the home page, are of type "page". Accessed via `.Page.Type` in [templates](g). See [details](/content-management/types/)
+A classification of content inferred from the top-level directory name or the `type` set in [front matter](g). Pages in the root of the `content` directory, including the home page, are of type "page". Accessed via `.Page.Type` in [templates](g).

content/en/getting-started/glossary/content-view.md

@@ -1,5 +1,6 @@
 ---
 title: content view
+reference: /templates/content-view
 ---
 
-A template called with the `.Page.Render` method. See [details](/templates/content-view/).
+A template called with the `.Page.Render` method.

content/en/getting-started/glossary/context.md

@@ -1,5 +1,6 @@
 ---
 title: context
+reference: /templates/introduction/#context
 ---
 
-Represented by a dot "." within a [template action](g), context is the current location in a data structure. For example, while iterating over a [collection](g) 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 [details](/templates/introduction/#context).
+Represented by a dot "." within a [template action](g), context is the current location in a data structure. For example, while iterating over a [collection](g) 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.

content/en/getting-started/glossary/flag.md

@@ -1,5 +1,6 @@
 ---
 title: flag
+reference: /commands/hugo
 ---
 
-An option passed to a command-line program, beginning with one or two hyphens. See [details](/commands/hugo/).
+An option passed to a command-line program, beginning with one or two hyphens.

content/en/getting-started/glossary/front-matter.md

@@ -1,5 +1,6 @@
 ---
 title: front matter
+reference: /content-management/front-matter
 ---
 
-Metadata at the beginning of each content page, separated from the content by format-specific delimiters. See [details](/content-management/front-matter/).
+Metadata at the beginning of each content page, separated from the content by format-specific delimiters.

content/en/getting-started/glossary/function.md

@@ -1,5 +1,6 @@
 ---
 title: function
+reference: /functions
 ---
 
-Used within a [template action](g), a function takes one or more [arguments](g) and returns a value. Unlike [methods](g), functions are not associated with an [object](g). See [details](/functions/).
+Used within a [template action](g), a function takes one or more [arguments](g) and returns a value. Unlike [methods](g), functions are not associated with an [object](g). 

content/en/getting-started/glossary/interpreted-string-literal.md

@@ -2,4 +2,4 @@
 title: interpreted string literal
 ---
 
-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).
+An _interpreted string literal_ is a 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).

content/en/getting-started/glossary/leaf-bundle.md

@@ -2,4 +2,4 @@
 title: leaf bundle
 ---
 
-A directory that contains an index.md file and zero or more [resources](g). Analogous to a physical leaf, a leaf bundle is at the end of a branch. It has no descendants. See [details](/content-management/page-bundles/).
+A directory that contains an `index.md` file and zero or more [resources](g). Analogous to a physical leaf, a leaf bundle is at the end of a branch. It has no descendants. See [details](/content-management/page-bundles/).

content/en/getting-started/glossary/pagination.md

@@ -1,5 +1,6 @@
 ---
 title: pagination
+reference: /templates/pagination
 ---
 
-The process of [paginating](g) a list page. See [details](/templates/pagination/).
+The process of [paginating](g) a list page.

content/en/getting-started/glossary/pipeline.md

@@ -4,4 +4,4 @@ title: pipeline
 
 Within a [template action](g), a pipeline is a possibly chained sequence of values, [function](g) calls, or [method](g) calls. Functions and methods in the pipeline may take multiple [arguments](g).
 
-A pipeline may be *chained* by separating a sequence of commands with pipeline characters "|". In a chained pipeline, the result of each command is passed as the last argument to the following command. The output of the final command in the pipeline is the value of the pipeline. See the [Go documentation](https://pkg.go.dev/text/template#hdr-Pipelines) for details.
+A pipeline may be *chained* by separating a sequence of commands with pipeline characters "|". In a chained pipeline, the result of each command is passed as the last argument to the following command. The output of the final command in the pipeline is the value of the pipeline.

content/en/getting-started/glossary/raw-string-literal.md

@@ -2,4 +2,4 @@
 title: raw string literal
 ---
 
-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).
+A _raw string literal_ is a 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.

content/en/getting-started/glossary/render-hook.md

@@ -1,5 +1,6 @@
 ---
 title: render hook
+reference: /render-hooks
 ---
 
-A [template](g) that overrides standard Markdown rendering. See [details](/render-hooks).
+A [template](g) that overrides standard Markdown rendering.

content/en/getting-started/glossary/section.md

@@ -2,4 +2,4 @@
 title: section
 ---
 
-A section is a top-level content directory, or any content directory with an `_index.md` file. A content directory with an `_index.md` file is also known as a [branch bundle](g). Section templates receive one or more page [collections](g) in [context](g). See [details](/content-management/sections/).
+A _section_ is a top-level content directory or any content directory containing an `_index.md` file. A section is also known as a [_branch bundle_](g).