feat: Update Hugo and PR template guidance

.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 LINK 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).