content: Miscellaneous edits

jmooring · web-flow · commit f26ca047a567 · 2025-03-08T15:25:11.000-08:00
diff --git a/content/en/_common/gomodules-info.md b/content/en/_common/gomodules-info.md
@@ -2,7 +2,7 @@
 _comment: Do not remove front matter.
 ---
 
-> [!warning] Hugo Modules are Go Modules
+> [!note] Hugo Modules are Go Modules
 > You need [Go] version 1.18 or later and [Git] to use Hugo Modules. For older sites hosted on Netlify, please ensure the `GO_VERSION` environment variable is set to `1.18` or higher.
 >
 > Go Modules resources:
diff --git a/content/en/configuration/introduction.md b/content/en/configuration/introduction.md
@@ -230,7 +230,7 @@ The above sets the [`baseURL`], [`enableGitInfo`], and [`environment`] configura
 > [!note]
 > An environment variable takes precedence over the values set in the configuration file. This means that if you set a configuration value with both an environment variable and in the configuration file, the value in the environment variable will be used.
 
-Environment variables simplify configuration for CI/CD deployments like GitHub Pages, GitLab Pages, and Netlify by allowing you to set values directly within their respective configuration and workflow files.
+Environment variables simplify configuration for [CI/CD](g) deployments like GitHub Pages, GitLab Pages, and Netlify by allowing you to set values directly within their respective configuration and workflow files.
 
 > [!note]
 > Environment variable names must be prefixed with `HUGO_`.
diff --git a/content/en/content-management/image-processing/index.md b/content/en/content-management/image-processing/index.md
@@ -419,7 +419,7 @@ Examples using the sunset image from above:
 
 ## Image processing performance consideration
 
-Hugo caches processed images in the `resources` directory. If you include this directory in source control, Hugo will not have to regenerate the images in a CI/CD workflow (e.g., GitHub Pages, GitLab Pages, Netlify, etc.). This results in faster builds.
+Hugo caches processed images in the `resources` directory. If you include this directory in source control, Hugo will not have to regenerate the images in a [CI/CD](g) workflow (e.g., GitHub Pages, GitLab Pages, Netlify, etc.). This results in faster builds.
 
 If you change image processing methods or options, or if you rename or remove images, the `resources` directory will contain unused images. To remove the unused images, perform garbage collection with:
 
diff --git a/content/en/contribute/development.md b/content/en/contribute/development.md
@@ -109,7 +109,10 @@ go test ./...
 Commit your changes with a descriptive commit message:
 
 - Provide a summary on the first line, typically 50 characters or less, followed by a blank line.
-- Optionally, provide a detailed description where each line is 80 characters or less, followed by a blank line.
+  - Begin the summary with one of content, theme, config, all, or misc, followed by a colon, a space, and a brief description of the change beginning with a capital letter
+  - Use imperative present tense
+  - See the [commit message guidelines] for requirements
+- Optionally, provide a detailed description where each line is 72 characters or less, followed by a blank line.
 - Add one or more "Fixes" or "Closes" keywords, each on its own line, referencing the [issues] addressed by this change.
 
 For example:
@@ -125,8 +128,6 @@ Fixes #99998
 Closes #99999"
 ```
 
-See the [commit message guidelines] for details.
-
 ### Step 8
 
 Push the new branch to your fork of the documentation repository.
diff --git a/content/en/contribute/documentation.md b/content/en/contribute/documentation.md
@@ -26,7 +26,7 @@ Adhere to these Markdown conventions:
 - Use [ATX] headings (levels 2-4), not [setext] headings.
 - Use [fenced code blocks], not [indented code blocks].
 - Use hyphens, not asterisks, for unordered [list items].
-- Use the [callouts](#callouts) instead bold text for emphasis.
+- Use [callouts](#callouts) instead of bold text for emphasis.
 - Do not mix [raw HTML] within Markdown.
 - Do not use bold text in place of a heading or description term (`dt`).
 - Remove consecutive blank lines.
@@ -76,6 +76,16 @@ Link to the [glossary] as needed and use terms consistently. Pay particular atte
 - Avoid formatted strings.
 - Keep them concise.
 
+### Page descriptions
+
+When writing the page `description` use imperative present tense when possible. For example:
+
+{{< code-toggle file=content/en/functions/data/_index.md" fm=true >}}
+title: Data functions
+linkTitle: data
+description: Use these functions to read local or remote data files.
+{{< /code-toggle >}}
+
 ### Writing style
 
 Use active voice and present tense wherever possible.
@@ -102,7 +112,7 @@ Yes → Hugo is fast.
 
 ### Function and method descriptions
 
-Start descriptions in the functions and methods sections with "Returns" or "Reports whether" for boolean values.
+Start descriptions in the functions and methods sections with "Returns", of for booelan values, "Reports whether".
 
 ### File paths and names
 
@@ -260,47 +270,55 @@ draft = false
 
 ## Callouts
 
-Also known as admonitions, use callouts to visually highlight important information. The type (e.g., NOTE, TIP) is case-insensitive.
+To visually emphasize important information, use callouts (admonitions). Callout types are case-insensitive. Effective March 8, 2025, we utilize only three of the five available types.
+
+- note (272 instances)
+- warning (2 instances)
+- caution (1 instance)
+
+Limiting the number of callout types helps us to use them consistently.
 
 ```text
-> [!NOTE]
+> [!note]
 > Useful information that users should know, even when skimming content.
 ```
 
-> [!NOTE]
+> [!note]
 > Useful information that users should know, even when skimming content.
 
 ```text
-> [!TIP]
-> Helpful advice for doing things better or more easily.
+> [!warning]
+> Urgent info that needs immediate user attention to avoid problems.
 ```
 
-> [!TIP]
-> Helpful advice for doing things better or more easily.
+> [!warning]
+> Urgent info that needs immediate user attention to avoid problems.
 
 ```text
-> [!IMPORTANT]
-> Key information users need to know to achieve their goal.
+> [!caution]
+> Advises about risks or negative outcomes of certain actions.
 ```
 
-> [!IMPORTANT]
-> Key information users need to know to achieve their goal.
+> [!caution]
+> Advises about risks or negative outcomes of certain actions.
 
 ```text
-> [!WARNING]
-> Urgent info that needs immediate user attention to avoid problems.
+> [!tip]
+> Helpful advice for doing things better or more easily.
 ```
 
-> [!WARNING]
-> Urgent info that needs immediate user attention to avoid problems.
+> [!tip]
+> Helpful advice for doing things better or more easily.
 
 ```text
-> [!CAUTION]
-> Advises about risks or negative outcomes of certain actions.
+> [!important]
+> Key information users need to know to achieve their goal.
 ```
 
-> [!CAUTION]
-> Advises about risks or negative outcomes of certain actions.
+> [!important]
+> Key information users need to know to achieve their goal.
+
+
 
 ## Shortcodes
 
@@ -460,7 +478,7 @@ Commit your changes with a descriptive commit message:
   - Begin the summary with one of `content`, `theme`, `config`, `all`, or `misc`, followed by a colon, a space, and a brief description of the change beginning with a capital letter
   - Use imperative present tense
 - Optionally, provide a detailed description where each line is 72 characters or less, followed by a blank line.
-- Optionally, add one or more "Fixes" (for bugs) or "Closes" (for enhancements) keywords, each on its own line, referencing the [issues] addressed by this change.
+- Optionally, add one or more "Fixes" or "Closes" keywords, each on its own line, referencing the [issues] addressed by this change.
 
 For example:
 
diff --git a/content/en/functions/css/Sass.md b/content/en/functions/css/Sass.md
@@ -123,7 +123,7 @@ Run `hugo env` to list the active transpilers.
 
 ### Installing in a production environment
 
-For [CI/CD] deployments (e.g., GitHub Pages, GitLab Pages, Netlify, etc.) you must edit the workflow to install Dart Sass before Hugo builds the site[^2]. Some providers allow you to use one of the package managers above, or you can download and extract one of the prebuilt binaries.
+For [CI/CD](g) deployments (e.g., GitHub Pages, GitLab Pages, Netlify, etc.) you must edit the workflow to install Dart Sass before Hugo builds the site[^2]. Some providers allow you to use one of the package managers above, or you can download and extract one of the prebuilt binaries.
 
 [^2]: You do not have to do this if (a) you have not modified the assets cache location, and (b) you have not set `useResourceCacheWhen` to `never` in your [site configuration], and (c) you add and commit your `resources` directory to your repository.
 
@@ -224,7 +224,6 @@ If you build Hugo from source and run `mage test -v`, the test will fail if you
 
 [brew.sh]: https://brew.sh/
 [chocolatey.org]: https://community.chocolatey.org/packages/sass
-[ci/cd]: https://en.wikipedia.org/wiki/CI/CD
 [dart sass]: https://sass-lang.com/dart-sass
 [libsass]: https://sass-lang.com/libsass
 [prebuilt binaries]: https://github.com/sass/dart-sass/releases/latest
diff --git a/content/en/functions/css/TailwindCSS.md b/content/en/functions/css/TailwindCSS.md
@@ -93,7 +93,7 @@ Create a partial template to process the CSS with the Tailwind CSS CLI:
 
 Call the partial template from your base template:
 
-```go-html-template {file="layouts/default/baseof.html"}
+```go-html-template {file="layouts/_default/baseof.html"}
 <head>
   ...
   {{ partialCached "css.html" . }}
diff --git a/content/en/getting-started/usage.md b/content/en/getting-started/usage.md
@@ -142,7 +142,7 @@ public/
 
 In a simple hosting environment, where you typically `ftp`, `rsync`, or `scp` your files to the root of a virtual host, the contents of the `public` directory are all that you need.
 
-Most of our users deploy their sites using a CI/CD workflow, where a push[^1] to their GitHub or GitLab repository triggers a build and deployment. Popular providers include [AWS Amplify], [CloudCannon], [Cloudflare Pages], [GitHub Pages], [GitLab Pages], and [Netlify].
+Most of our users deploy their sites using a [CI/CD](g) workflow, where a push[^1] to their GitHub or GitLab repository triggers a build and deployment. Popular providers include [AWS Amplify], [CloudCannon], [Cloudflare Pages], [GitHub Pages], [GitLab Pages], and [Netlify].
 
 Learn more in the [host and deploy] section.
 
diff --git a/content/en/host-and-deploy/host-on-firebase.md b/content/en/host-and-deploy/host-on-firebase.md
@@ -60,7 +60,7 @@ Here is your opportunity to include some commands before you run the deploy.
 
 You can let in the default option (main)
 
-After that Firebase has been set in your project with CI/CD. After that run:
+After that Firebase has been set in your project with [CI/CD](g). After that run:
 
 ```sh
 hugo && firebase deploy
diff --git a/content/en/host-and-deploy/host-on-gitlab-pages.md b/content/en/host-and-deploy/host-on-gitlab-pages.md
@@ -19,7 +19,7 @@ The `baseURL` in your [site configuration](/configuration/) must reflect the ful
 
 ## Configure GitLab CI/CD
 
-Define your [CI/CD](https://docs.gitlab.com/ee/ci/quick_start/) jobs by creating a `.gitlab-ci.yml` file in the root of your project.
+Define your [CI/CD](g) jobs by creating a `.gitlab-ci.yml` file in the root of your project.
 
 ```yaml {file=".gitlab-ci.yml" copy=true}
 variables:
diff --git a/content/en/methods/page/GitInfo.md b/content/en/methods/page/GitInfo.md
@@ -125,7 +125,7 @@ You can change this behavior in your [site configuration].
 
 ## Hosting considerations
 
-When hosting your site in a CI/CD environment, the step that clones your project repository must perform a deep clone. If the clone is shallow, the Git information for a given file may not be accurate---it may reflect the most recent repository commit, not the commit that last modified the file.
+When hosting your site in a [CI/CD](g) environment, the step that clones your project repository must perform a deep clone. If the clone is shallow, the Git information for a given file may not be accurate---it may reflect the most recent repository commit, not the commit that last modified the file.
 
 Some providers perform deep clones by default, others allow you to configure the clone depth, and some only perform shallow clones.
 
diff --git a/content/en/quick-reference/glossary/cicd.md b/content/en/quick-reference/glossary/cicd.md
@@ -0,0 +1,7 @@
+---
+title: CI/CD
+params:
+  reference: https://en.wikipedia.org/wiki/CI/CD
+---
+
+The term _CI/CD_ is an abbreviation for Continuous Integration and Continuous Delivery or Continuous Deployment depending on context.
diff --git a/content/en/showcase/ampio-help/index.md b/content/en/showcase/ampio-help/index.md
@@ -67,7 +67,7 @@ Very quickly it became apparent that our initial concerns about the adaptation o
 
 We recommended that our colleagues use Visual Studio Code as a tool for content creation. The project's repository tracks project-scoped configuration of the editor, which includes a set of _tasks_ allowing to run a live server from the GUI level. This is very useful for those who are easily frightened when faced with the mighty terminal.
 
-The basic skills of the Git workflow were also easily acquired. At the end of the day, builds and deployments are fully managed by CI/CD processes, so the administration of the service drills down to reviewing and accepting merge requests in the Git frontend. As a side effect, we receive a full and clear history of contributions, which is well appreciated by our quality assurance auditors.
+The basic skills of the Git workflow were also easily acquired. At the end of the day, builds and deployments are fully managed by [CI/CD](g) processes, so the administration of the service drills down to reviewing and accepting merge requests in the Git frontend. As a side effect, we receive a full and clear history of contributions, which is well appreciated by our quality assurance auditors.
 
 We could even say that our experiment spread the love for Git among non-programmers in our organization!
 
diff --git a/content/en/templates/base.md b/content/en/templates/base.md
@@ -61,10 +61,10 @@ The default list template will inherit all of the code defined above and can the
 
 This replaces the contents of our (basically empty) `main` block with something useful for the list template. In this case, we didn't define a `title` block, so the contents from our base template remain unchanged in lists.
 
-> [!caution]
+> [!warning]
 > Only [template comments] are allowed outside a block's `define` and `end` statements. Avoid placing any other text, including HTML comments, outside these boundaries. Doing so will cause rendering issues, potentially resulting in a blank page. See the example below.
 
-```go-html-template {file="layouts/default/single.html"}
+```go-html-template {file="layouts/_default/do-not-do-this.html"}
 <div>This div element broke your template.</div>
 {{ define "main" }}
   <h2>{{ .Title }}</h2>
diff --git a/layouts/_default/_markup/render-link.html b/layouts/_default/_markup/render-link.html
@@ -292,6 +292,7 @@
     "localized" "localization"
     "paginating" "paginate"
     "walking" "walk"
+    "ci/cd" "cicd"
   }}
 
   {{- /* Verify that a glossary term page exists for the given term. */}}

Original file line number	Diff line number	Diff line change
`@@ -2,7 +2,7 @@`
`2`	`2`	`_comment: Do not remove front matter.`
`3`	`3`	`---`
`4`	`4`
`5`		`-> [!warning] Hugo Modules are Go Modules`
	`5`	`+> [!note] Hugo Modules are Go Modules`
`6`	`6`	> You need [Go] version 1.18 or later and [Git] to use Hugo Modules. For older sites hosted on Netlify, please ensure the `GO_VERSION` environment variable is set to `1.18` or higher.
`7`	`7`	`>`
`8`	`8`	`> Go Modules resources:`