Merge branch 'main' into ngf/use-server-side-apply

ADubhlaoich · web-flow · commit e071f336e776 · 2025-07-04T15:06:15.000+01:00
diff --git a/.github/ISSUE_TEMPLATE/1-feature_request.md b/.github/ISSUE_TEMPLATE/1-feature_request.md
@@ -2,7 +2,7 @@
 name: Feature request
 about: Suggest an idea for this project
 title: ""
-labels: ""
+labels: "enhancement"
 assignees: ""
 ---
 
diff --git a/.github/ISSUE_TEMPLATE/2-bug_report.md b/.github/ISSUE_TEMPLATE/2-bug_report.md
@@ -2,7 +2,7 @@
 name: Bug report
 about: Create a report to help us improve
 title: ""
-labels: ""
+labels: "bug"
 assignees: ""
 ---
 
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -26,10 +26,10 @@ Before merging a pull request, run through this checklist and mark each as compl
 - [ ] 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](https://github.com/nginx/documentation/blob/main/templates/style-guide.md)
+- [ ] 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`](https://github.com/nginx/documentation/blob/main/README.md) and [`CHANGELOG.md`](https://github.com/nginx/documentation/blob/main/CHANGELOG.md)
+- [ ] If applicable, I have updated [`README.md`](/README.md)
 
-[^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](https://github.com/nginx/documentation/blob/main/templates/style-guide.md) for guidance about placeholder content.
+[^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.
diff --git a/CHANGELOG.md b/CHANGELOG.md
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,38 +1,36 @@
 # Contributing guidelines
 
-The following is a set of guidelines for community contributions to this project.
-
-We really appreciate your desire to contribute!
+The following are a set of guidelines for contributing to this project. We appreciate your desire to get involved!
 
 If you are an F5 employee, see the following additional guidance on [Maintainers etiquette](/documentation/maintainers-etiquette.md).
 
 ## Table of contents
 
-- [Report a Bug](#report-a-bug)
-- [Suggest a Feature or Enhancement](#suggest-a-feature-or-enhancement)
-- [Open a Discussion](#open-a-discussion)
+- [Create an issue](#create-an-issue)
+- [Start a discussion](#start-a-discussion)
 - [Submit a pull request](#submit-a-pull-request)
-- [Issue Lifecycle](#issue-lifecycle)
+- [Issue lifecycle](#issue-lifecycle)
 - [Additional NGINX documentation](#additional-nginx-documentation)
 - [F5 Contributor License Agreement (CLA)](#f5-contributor-license-agreement)
 
-## Report a bug
+## Create an issue
+
+One way to contribute to the project is by [creating an issue](https://github.com/nginx/documentation/issues/new/choose).
+
+The two most common are enhancements and bug reports. When using the issue templates, they will be automatically labelled.
+
+- An enhancement is an improvement of some kind, such as a new document or additional detail for a product feature
+- A bug report draws attention to an issue in documentation, such as an incorrect command or outdated information
 
-To report a bug, open an issue on GitHub with the label `bug` using the
-available bug report issue template. Before reporting a bug, make sure the
-issue has not already been reported.
+Before creating an issue, please check there is [no existing issue](https://github.com/nginx/documentation/issues?q=is%3Aissue) for the topic.
 
-## Suggest a feature or enhancement
+We encourage discussions within issues, since they act as a source of contextual truth and are linked to pull requests.
 
-To suggest a feature or enhancement, open an issue on GitHub with the label
-`feature` or `enhancement` using the available feature request issue template.
-Please ensure the feature or enhancement has not already been suggested.
+## Start a discussion
 
-## Open a Discussion
+We encourage you to use [GitHub Discussions](https://github.com/nginx/documentation/discussions) for conversations with the community and maintainers.
 
-If you want to start a conversation with the community and maintainers,
-we encourage you to use
-[GitHub Discussions](https://github.com/nginx/documentation/discussions).
+If you'd like to discuss something NGINX-related that doesn't involve documentation, you should go to the [NGINX Community Forum](https://community.nginx.org/). 
 
 ## Submit a pull request
 
@@ -66,7 +64,6 @@ This repository does not include all of the source content for the NGINX documen
 - [NGINX Open Source](https://github.com/nginx/nginx) - source for [NGINX changelog](https://nginx.org/en/CHANGES)
 - [nginx.org](https://github.com/nginx/nginx.org) - source for https://nginx.org
 - [NGINX Unit](https://github.com/nginx/unit) - source for https://unit.nginx.org
-- [NGINX Ingress Controller](https://github.com/nginxinc/kubernetes-ingress/) - source for https://docs.nginx.com/nginx-ingress-controller
 
 In those repositories, you can find documentation source code in the `docs` or `site` subdirectories.
 
diff --git a/README.md b/README.md
@@ -4,33 +4,28 @@
 [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](https://github.com/nginxinc/template-repository/main/CODE_OF_CONDUCT.md)
 ![Commercial Support](https://badgen.net/badge/support/commercial/green?icon=awesome)
 
-<!-- These are the "repo [status badge](https://www.repostatus.org/)s" and the community support badges -->
-
 # NGINX documentation
 
+This repository contains the user documentation for NGINX's products, as well as the requirements to build and publish the documentation website.
+
+Documentation is written in [Markdown](https://daringfireball.net/projects/markdown/basics), then transformed into HTML using the [Hugo](https://gohugo.io/) static site generator.
+
 If you want to contribute to [F5 NGINX documentation](https://docs.nginx.com), you've come to the right place. We've organized a series of README-type files to help you get started:
 
 - [Contributing](/CONTRIBUTING.md) describes how you can contribute to our documentation.
-  - [Contributing guidelines for experts](/CONTRIBUTING_DOCS.md) describes how you can contribute (and check your work) with Hugo, our static site generator
 - [Code of Conduct](/CODE_OF_CONDUCT.md) describes expectations in the NGINX open source community.
 - [License](/LICENSE) shows the license associated with work on this repository.
 - [Security](/SECURITY.md) describes the procedures we would like you to follow if you find a security issue.
 - [Support](/SUPPORT.md) lists how you can get support as a customer or a community member.
 
-## Explanation
-
-This repository contains user documentation for NGINX's products, as well as the requirements for linting, building, and publishing the documentation.
-
-Our documentation is written in Markdown, specifically the [Goldmark](https://github.com/yuin/goldmark) Markdown parser.
-We build our docs using [Hugo](https://gohugo.io) and host them in custom URLs on Azure.
+You may also find the [documentation folder](/documentation/) for the repository interesting: it's where we store our process information.
 
 ## License
 
 [BSD 2-Clause "Simplified" License](/LICENSE)
 
 &copy; [F5, Inc.](https://www.f5.com/) 2025
 
-
 ## Credits
 
 - [The Good Docs Project](https://www.thegooddocsproject.dev/), whose templates we've adapted for our use.
diff --git a/documentation/writing-hugo.md b/documentation/writing-hugo.md
@@ -4,50 +4,35 @@ This page describes our guidelines on using [Hugo](https://gohugo.io/) to write
 
 You will need [git](https://git-scm.com/) to interact with the repository and files: the content itself is written in Markdown.
 
-Our workflow is to develop content locally, then submit a pull request once we've done our initial draft and editing passes.
+Our workflow is to develop content locally, then [submit a pull request](/documentation/git-conventions.md) once we've done our initial draft and editing passes.
 
 For guidance around how to write content, please check [the style guide](/documentation/style-guide.md).
 
 ## Setup
 
-You will need to install Hugo _or_ Docker to build and preview docs in your local development environment.
+You will need to install Hugo _or_ Docker to build or preview documentation in your local development environment.
 
-Read the [Hugo installation instructions](https://gohugo.io/getting-started/installing/) for more information.
+Read the [Hugo installation instructions](https://gohugo.io/getting-started/installing/) for more information: we are currently running [Hugo v0.147.8](https://github.com/gohugoio/hugo/releases/tag/v0.147.8) in production.
 
 If you have [Docker](https://www.docker.com/get-started/) installed, there are fallbacks for all requirements in the [Makefile](Makefile), meaning you don't need to install them.
 
-- [Installing Hugo](https://gohugo.io/getting-started/installing/)
-  - **NOTE**: We are currently running [Hugo v0.147.8](https://github.com/gohugoio/hugo/releases/tag/v0.147.8) in production.
-- [Installing markdownlint-cli](https://github.com/igorshubovych/markdownlint-cli?tab=readme-ov-file#installation)
-- [Installing markdown-link-check](https://github.com/tcort/markdown-link-check?tab=readme-ov-file#installation)
+## Build the documentation locally
 
-The configuration files are as follows:
-
-- *Hugo*: `config/default/config.toml`
-- *markdownlint-cli*: `.markdownlint.json`
-- *markdown-link-check* `md-linkcheck-config.json`
-
-## Develop documentation locally
-
-To build the documentation website locally, use the `make` command in the documentation folder. 
-
-First ensure you have the latest version of the Hugo theme with:
+To build the website locally, first ensure you have the latest version of the Hugo theme with:
 
 `make hugo-update`
 
-Once you've updated the theme, you can use these targets:
+You can then use the other `make` commands: *watch* is most commmon when working on documentation.
 
 | Target              | Description                                                                 |
 | ------------------- | --------------------------------------------------------------------------- |
 | _make watch_        | Runs a local Hugo server, allowing for changes to be previewed in a browser. |
 | _make drafts_       | Runs a local Hugo server, rendering documents marked with `draft: true` in their metadata.|
-| _make docs_          | Builds the documentation in the local `public/` directory. |
-| _make clean_         | Removes the local `public` directory |
-| _make hugo-get_      | Updates the go module file with the latest version of the theme. |
-| _make hugo-tidy_     | Removes unnecessary dependencies from the go module file. |
-| _make hugo-update_   | Runs the hugo-get and hugo-tidy targets in sequence. |
-| _make lint-markdown_ | Runs [markdownlint](https://github.com/DavidAnson/markdownlint) on the content folder. |
-| _make link-check_    | Runs [markdown-link-check](https://github.com/tcort/markdown-link-check) on all Markdown files. |
+| _make docs_         | Builds the documentation in the local `public/` directory. |
+| _make clean_        | Removes the local `public` directory |
+| _make hugo-get_     | Updates the go module file with the latest version of the theme. |
+| _make hugo-tidy_    | Removes unnecessary dependencies from the go module file. |
+| _make hugo-update_  | Runs the hugo-get and hugo-tidy targets in sequence. |
 
 ## Add new documentation
 
@@ -67,9 +52,10 @@ This new page will be created with the default how-to archetype. To use a specif
 
 Our archetypes [currently include](/archetypes/) the following:
 
-- `default` (How-to instructions, general use)
-- `concept`(An explanation of one implementation detail and some use cases)
-- `tutorial` (An in-depth set of how-to instructions, referencing concepts)
+- `default` - How-to instructions, general use
+- `concept` - An explanation of one implementation detail and some use cases
+- `tutorial` - An in-depth set of how-to instructions, referencing concepts
+- `landing-page` - A special archetype for the landing page of a documentation set, with a unique layout
 
 These archetypes are adapted from some existing [templates](/templates/): please [file an issue](https://github.com/nginx/documentation/issues/new?template=1-feature_request.md) if you would like a new archetype.
 
@@ -165,11 +151,11 @@ An example of this can be seen in [/content/ngf/get-started.md](https://github.c
 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.
-1. Add the `img` shortcode:
+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](/templates/style-guide.md#guidelines-for-screenshots).
+> **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
