feat: Update Hugo and PR template guidance (#894)

This commit updates the Hugo guidance to accurately reflect the usage of
our most common shortcodes, and guides people away from the ones that
have been removed or will be removed soon based on Mainframe changes.

The guidance is not fully inclusive: we have not yet determined where
full documentation for all theme elements should live (Such as a
publicly-facing design system), but it should cover the most commonly
used shortcodes.

The pull request template has also been updated in the same manner,
attempting to focus on critical information for contributors. The
checklist was previously quite long: it has been reduced to essential
elements, and reframed as a direct, personal commitment.

The detail underneath the "Proposed changes" has been shifted to inline,
hidden guidance, following a similar pattern in our Hugo archetypes.
Some information from the old checklist has been moved there, but it
otherwise covers the same ground as the old guidance.

It refers to and reinforces our standards asserted by our Git
conventions documentation, and will not create visual noise within the
PR should the contributor choose not to remove it.

Author: ADubhlaoich

.github/pull_request_template.md

@@ -1,35 +1,31 @@
 ### Proposed changes
 
-Write a clear and concise description that helps reviewers understand the purpose and impact of your changes. Use the
-following format:
+[//]: # "Write a clear and concise description of what the pull request changes."
+[//]: # "You can use our Commit messages guidance for this."
+[//]: # "https://github.com/nginx/documentation/blob/main/documentation/git-conventions.md#commit-messages"
 
-Problem: Give a brief overview of the problem or feature being addressed.
+[//]: # "First, explain what was changed, and why. This should be most of the detail."
+[//]: # "Then how the changes were made, such as referring to existing styles and conventions."
+[//]: # "Finish by noting anything beyond the scope of the PR changes that may be affected."
 
-Solution: Explain the approach you took to implement the solution, highlighting any significant design decisions or
-considerations.
+[//]: # "Include information on testing if relevant and non-obvious from the deployment preview."
+[//]: # "For expediency, you can use screenshots to show small before and after examples."
 
-Testing: Describe any testing that you did.
+[//]: # "If the changes were defined by a GitHub issue, reference it using keywords."
+[//]: # "https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests"
 
-Please focus on (optional): If you any specific areas where you would like reviewers to focus their attention or provide
-specific feedback, add them here.
-
-If this PR addresses an [issue](https://github.com/nginx/documentation/issues) on GitHub, ensure that you link to it here:
-
-Closes #ISSUE
+[//]: # "Do not like to any internal, non-public resources. This includes internal repository issues or anything in an intranet."
+[//]: # "You can make reference to internal discussions without linking to them: see 'Referencing internal information'."
+[//]: # "https://github.com/nginx/documentation/blob/main/documentation/closed-contributions.md#referencing-internal-information"
 
 ### Checklist
 
-Before merging a pull request, run through this checklist and mark each as complete.
+Before sharing this pull request, I completed the following checklist:
 
-- [ ] I have read the [contributing guidelines](https://github.com/nginx/documentation/blob/main/CONTRIBUTING.md)
-- [ ] I have signed the [F5 Contributor License Agreement (CLA)](https://github.com/f5/.github/blob/main/CLA/cla-markdown.md)
-- [ ] I have rebased my branch onto main
-- [ ] I have ensured my PR is targeting the main branch and pulling from my branch from my own fork
-- [ ] I have ensured that the commit messages adhere to [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary)
-- [ ] I have ensured that documentation content adheres to [the style guide](/documentation/style-guide.md)
-- [ ] If the change involves potentially sensitive changes[^1], I have assessed the possible impact
-- [ ] If applicable, I have added tests that prove my fix is effective or that my feature works
-- [ ] I have ensured that existing tests pass after adding my changes
-- [ ] If applicable, I have updated [`README.md`](/README.md)
+- [ ] I read the [Contributing guidelines](/CONTRIBUTING.md)
+- [ ] My branch adheres to the [Git conventions](/documentation/git-conventions.md)
+- [ ] My content changes adhere to the [F5 NGINX Documentation style guide](/documentation/style-guide.md)
+- [ ] If my changes involve potentially sensitive information[^1], I have assessed the possible impact
+- [ ] I have waited to ensure my changes pass tests, and addressed any discovered issues
 
-[^1]: Potentially sensitive changes include anything involving code, personally identify information (PII), live URLs or significant amounts of new or revised documentation. Please refer to [our style guide](/documentation/style-guide.md) for guidance about placeholder content.
+[^1]: Potentially sensitive information includes personally identify information (PII), authentication credentials, and live URLs. Refer to the [style guide](/documentation/style-guide.md) for guidance about placeholder content.

documentation/closed-contributions.md

@@ -11,6 +11,19 @@ We work in public by default, so this process should only be used on a case by c
 
 For standard content releases, review the [Contributing guidelines](/CONTRIBUTING.md).
 
+## Referencing internal information
+
+During the last stage of this process, or while making any public pull request, you may need to reference something internal.
+
+As mentioned in our pull request template checklist, you should not link to internal resources: they are considered "sensitive content", defined previously.
+
+Instead, include the key outputs of the internal resource as part of describing context:
+
+> "Following an internal discussion, the instructions for foo have been clarified"  
+> "The phrasing of bar has been changed based on an internal requirement"
+
+This allows you to retain the necessary context for a change without exposing a potentially important resource to the public.
+
 ## Overview
 
 This repository (https://github.com/nginx/documentation) is where we work by default. It has a one-way sync to an internal repository, used for closed content.

documentation/writing-hugo.md

@@ -87,53 +87,58 @@ To install <integation>, refer to the [integration instructions]({{< ref "/integ
 
 ### How to use Hugo shortcodes
 
-[Hugo shortcodes](https://github.com/nginxinc/nginx-hugo-theme/tree/main/layouts/shortcodes) are used to format callouts, add images, and reuse content across different pages.
+[Hugo shortcodes](https://github.com/nginxinc/nginx-hugo-theme/tree/main/layouts/shortcodes) are used to provide extra functionality and special formatting to Markdown content.
 
-For example, to use the `note` callout:
+This is an example of a call-out shortcode:
 
 ```md
-{{< note >}} Provide the text of the note here .{{< /note >}}
+{{< call-out "note" >}} Provide the text of the note here .{{< /call-out >}}
 ```
 
-The callout shortcodes support multi-line blocks:
+Here are some other shortcodes:
+
+- `include`: Include the content of a file in another file: read the [Re-use content with includes](#re-use-content-with-includes) instructions
+- `tabs`: Create mutually exclusive tabbed window panes, useful for parallel instructions
+- `table`: Add scrollbars to wide tables for browsers with smaller viewports
+- `icon`: Add a [Lucide icon](https://lucide.dev/icons/) by using its name as a parameter
+- `link`: Link to a file, prepending its path with the Hugo baseUrl
+- `ghcode`: Embeds the contents of a code file: read the [Add code to documentation pages](#add-code-to-documentation-pages) instructions
+- `openapi`: Loads an OpenAPI specification and render it as HTML using ReDoc
+
+#### Add call-outs to documentation pages
+
+The call out shortcode support multi-line blocks:
 
 ```md
-{{< caution >}}
+{{< call-out "caution" >}}
 You should probably never do this specific thing in a production environment.
 
 If you do, and things break, don't say we didn't warn you.
-{{< /caution >}}
+{{< /call-out >}}
 ```
 
-Supported callouts:
+The first parameter determines the type of call-out, which defines the colour given to it.
+
+Supported types:
 - `note`
 - `tip`
 - `important`
 - `caution`
 - `warning`
 
-You can also create custom callouts using the `call-out` shortcode `{{< call-out "type position" "header" "font-awesome icon >}}`. For example:
+An optional second parameter will add a title to the call-out: without it, it will fall back to the type.
 
 ```md
-{{<call-out "important side-callout" "JWT file required for upgrade" "fa fa-exclamation-triangle">}}
-```
+{{< call-out "important" "This instruction only applies to v#.#.#" >}}
+These instructions are only intended for versions #.#.# onwards.
 
-By default, all custom callouts are displayed inline, unless you add `side-callout` which places the callout to the right of the content.
-
-Here are some other shortcodes:
+Follow <these-instructions> if you're using an older version.
+{{< /call-out >}}
+```
 
-- `fa`: Inserts a Font Awesome icon
-- `collapse`: Make a section collapsible
-- `tab`: Create mutually exclusive tabbed window panes, useful for parallel instructions
-- `table`: Add scrollbars to wide tables for browsers with smaller viewports
-- `link`: Link to a file, prepending its path with the Hugo baseUrl
-- `openapi`: Loads an OpenAPI specification and render it as HTML using ReDoc
-- `include`: Include the content of a file in another file; the included file must be present in the '/content/includes/' directory
-- `raw-html`: Include a block of raw HTML
-- `readfile`: Include the content of another file in the current file, which can be in an arbitrary location.
-- `bootstrap-table`: formats a table using Bootstrap classes; accepts any bootstrap table classes as additional arguments, e.g. `{{< bootstrap-table "table-bordered table-hover" }}`
+Finally, you can use an optional third parameter to add a [Lucide icon](https://lucide.dev/icons/) using its name.
 
-### Add code to documentation pages
+#### Add code to documentation pages
 
 For command, binary, and process names, we sparingly use pairs of backticks (\`\<some-name\>\`): `<some-name>`.
 
@@ -145,22 +150,9 @@ You can also use the `ghcode` shortcode to embed a single file directly from Git
 
 An example of this can be seen in [/content/ngf/get-started.md](https://github.com/nginx/documentation/blob/af8a62b15f86a7b7be7944b7a79f44fd5e526c15/content/ngf/get-started.md?plain=1#L233C1-L233C128), which embeds a YAML file.
 
+#### Re-use content with includes
 
-### Add images to documentation pages
-
-Use the `img` shortcode to add images to documentation pages. It has the same parameters as the Hugo [figure shortcode](https://gohugo.io/content-management/shortcodes/#figure).
-
-1. Add the image to the `/static/img` directory.
-2. Add the `img` shortcode:
-  - `{{< img src="<img-file.png>" alt="<Alternative text>">}}`
-  - Do not include a forward slash at the beginning of the file path or it will [break the image](https://gohugo.io/functions/relurl/#input-begins-with-a-slash).
-
-> **Important**: We have strict guidelines for using images. Review them in our [style guide](/documentation/style-guide.md#guidelines-for-screenshots).
-
-
-### How to use Hugo includes
-
-Hugo includes are a custom shortcode that allows you to embed content stored in the [`/content/includes` directory](https://github.com/nginx/documentation/tree/main/content/includes).
+The includes are a custom shortcode that allows you to embed content stored in the [`/content/includes` directory](https://github.com/nginx/documentation/tree/main/content/includes).
 
 It allows for content to be defined once and display in multiple places without duplication, creating consistency and simplifying the maintenance of items such as reference tables.
 
@@ -180,12 +172,13 @@ This particular include file is used in the following pages:
 
 View the [Guidelines for includes](/templates/style-guide.md#guidelines-for-includes) for instructions on how to write effective include files.
 
-## Linting
+#### Add images to documentation pages
 
-To use markdownlint to check content, run the following command:
+Use the `img` shortcode to add images to documentation pages. It has the same parameters as the Hugo [figure shortcode](https://gohugo.io/content-management/shortcodes/#figure).
 
-```shell
-markdownlint -c .markdownlint.yaml </content/path>
-```
+1. Add the image to the `/static/img` directory.
+2. Add the `img` shortcode:
+  - `{{< img src="<img-file.png>" alt="<Alternative text>">}}`
+  - Do not include a forward slash at the beginning of the file path or it will [break the image](https://gohugo.io/functions/relurl/#input-begins-with-a-slash).
 
-The content path can be an individual file or a folder.
+> **Important**: We have strict guidelines for using images. Review them in our [style guide](/documentation/style-guide.md#guidelines-for-screenshots).