Skip to content

Commit a19a2c4

Browse files
JTorreGJTorreG
authored
Merge branch 'main' into unit-docs
2 parents 2da5e96 + f2fb270 commit a19a2c4

File tree

92 files changed

+2246
-2930
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

92 files changed

+2246
-2930
lines changed

‎.github/CODEOWNERS‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,10 @@ content/nap-dos/* @nginx/dos-docs-approvers
2929
content/nap-waf/* @nginx/nap-docs-approvers
3030
data/nap-waf/* @nginx/nap-docs-approvers
3131

32+
# NGINXaaS for Azure
33+
content/nginxaas-azure/* @nginx/n4a-docs
34+
content/includes/nginxaas-azure/* @nginx/n4a-docs
35+
3236
# NGINX Gateway Fabric
3337
content/ngf/* @nginx/nginx-gateway-fabric
3438
content/includes/ngf/* @nginx/nginx-gateway-fabric

‎.github/labeler.yml‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# Label PRs based on modified file paths (v5 format)
2+
# https://github.com/actions/labeler
3+
4+
# General documentation
5+
6+
documentation:
7+
- changed-files:
8+
- any-glob-to-any-file:
9+
- 'content/**'
10+
- 'assets/**'
11+
- 'static/**'
12+
- 'data/**'
13+
14+
# Product labels
15+
16+
product/agent:
17+
- changed-files:
18+
- any-glob-to-any-file:
19+
- 'content/agent/**'
20+
- 'content/includes/agent/**'
21+
22+
product/amplify:
23+
- changed-files:
24+
- any-glob-to-any-file: 'content/amplify/**'
25+
26+
product/controller:
27+
- changed-files:
28+
- any-glob-to-any-file:
29+
- 'content/controller/**'
30+
- 'content/includes/controller/**'
31+
32+
product/mesh:
33+
- changed-files:
34+
- any-glob-to-any-file: 'content/mesh/**'
35+
36+
product/modsec-waf:
37+
- changed-files:
38+
- any-glob-to-any-file: 'content/modsec-waf/**'
39+
40+
product/nap-dos:
41+
- changed-files:
42+
- any-glob-to-any-file:
43+
- 'content/nap-dos/**'
44+
- 'content/includes/nap-dos/**'
45+
46+
product/nap-waf:
47+
- changed-files:
48+
- any-glob-to-any-file:
49+
- 'content/nap-waf/**'
50+
- 'content/includes/nap-waf/**'
51+
52+
product/ngf:
53+
- changed-files:
54+
- any-glob-to-any-file:
55+
- 'content/ngf/**'
56+
- 'content/includes/ngf/**'
57+
58+
product/nginx-plus:
59+
- changed-files:
60+
- any-glob-to-any-file:
61+
- 'content/nginx/**'
62+
- 'content/includes/nginx-plus/**'
63+
64+
product/nginx-one:
65+
- changed-files:
66+
- any-glob-to-any-file:
67+
- 'content/nginx-one/**'
68+
- 'content/includes/nginx-one/**'
69+
70+
product/nginxaas:
71+
- changed-files:
72+
- any-glob-to-any-file:
73+
- 'content/nginxaas-azure/**'
74+
- 'content/includes/nginxaas-azure/**'
75+
76+
product/nim:
77+
- changed-files:
78+
- any-glob-to-any-file:
79+
- 'content/nim/**'
80+
- 'content/includes/nim/**'
81+
82+
product/nms:
83+
- changed-files:
84+
- any-glob-to-any-file:
85+
- 'content/nms/**'
86+
- 'content/includes/nms/**'
87+
88+
product/unit:
89+
- changed-files:
90+
- any-glob-to-any-file:
91+
- 'content/unit/**'
92+
- 'content/includes/unit/**'
93+
94+
# Other labels
95+
96+
process documentation:
97+
- changed-files:
98+
- any-glob-to-any-file:
99+
- 'templates/**'
100+
- '*.md'
101+
- 'LICENSE'
102+
103+
tooling:
104+
- changed-files:
105+
- any-glob-to-any-file:
106+
- 'layouts/**'
107+
- '.github/**'
108+
- '.cloudcannon/**'
109+
- 'styles/**'
110+
- 'layouts/**'
111+
- 'config/**'
112+
- 'archetypes/**'
113+
- '*.yml'
114+
- '*.yaml'
115+
- '*.json'
116+
- '*.ts'
117+
- '*.sh'
118+
- '*.js'
119+
- 'Makefile'
120+
- '.vale.ini'
121+
- '.gitignore'
122+
- '.gitattributes'

‎.github/pull_request_template.md‎

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -23,14 +23,13 @@ Before merging a pull request, run through this checklist and mark each as compl
2323

2424
- [ ] I have read the [contributing guidelines](https://github.com/nginx/documentation/blob/main/CONTRIBUTING.md)
2525
- [ ] I have signed the [F5 Contributor License Agreement (CLA)](https://github.com/f5/.github/blob/main/CLA/cla-markdown.md)
26+
- [ ] I have rebased my branch onto main
27+
- [ ] I have ensured my PR is targeting the main branch and pulling from my branch from my own fork
28+
- [ ] I have ensured that the commit messages adhere to [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary)
2629
- [ ] I have ensured that documentation content adheres to [the style guide](https://github.com/nginx/documentation/blob/main/templates/style-guide.md)
27-
- [ ] If the change involves potentially sensitive changes, I have assessed the possible impact
30+
- [ ] If the change involves potentially sensitive changes[^1], I have assessed the possible impact
2831
- [ ] If applicable, I have added tests that prove my fix is effective or that my feature works
29-
- [ ] If applicable, I have checked that any relevant tests pass after adding my changes
30-
- [ ] I have updated any relevant documentation ([`README.md`](https://github.com/nginx/documentation/blob/main/README.md) and [`CHANGELOG.md`](https://github.com/nginx/documentation/blob/main/CHANGELOG.md)
31-
- [ ] I have rebased my branch onto main
32-
- [ ] I will ensure my PR is targeting the main branch and pulling from my branch from my own fork
33-
34-
Potentially sensitive changes include anything involving code, personally identify information (PII), live URLs or significant amounts of new or revised documentation.
32+
- [ ] I have ensured that existing tests pass after adding my changes
33+
- [ ] 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)
3534

36-
Please refer to [our style guide](https://github.com/nginx/documentation/blob/main/templates/style-guide.md) for guidance about placeholder content.
35+
[^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.

‎.github/workflows/labeler.yml‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
name: PR Labeler
2+
3+
on:
4+
- pull_request_target
5+
6+
permissions:
7+
contents: read # Required to read the labeler.yml file
8+
pull-requests: write # Required to apply labels to PRs
9+
10+
jobs:
11+
label:
12+
runs-on: ubuntu-latest
13+
steps:
14+
- name: Apply labels based on file paths
15+
uses: actions/labeler@v5
16+
with:
17+
repo-token: "${{ secrets.GITHUB_TOKEN }}"

‎.github/workflows/linkchecker.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -104,7 +104,7 @@ jobs:
104104
# Run LinkChecker
105105
- name: Run LinkChecker on ${{ matrix.doc_paths }}
106106
continue-on-error: ${{ env.isProduction != 'true' }}
107-
uses: nick-fields/retry@7152eba30c6575329ac0576536151aca5a72780e # v3.0.0
107+
uses: nick-fields/retry@ce71cc2ab81d554ebbe88c79ab5975992d79ba08 # v3.0.2
108108
with:
109109
timeout_minutes: 10
110110
max_attempts: 3

‎.github/workflows/ossf_scorecard.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ jobs:
3434
persist-credentials: false
3535

3636
- name: Run analysis
37-
uses: ossf/scorecard-action@62b2cac7ed8198b15735ed49ab1e5cf35480ba46 # v2.4.0
37+
uses: ossf/scorecard-action@f49aabe0b5af0936a0987cfb85d86b75731b0186 # v2.4.1
3838
with:
3939
results_file: results.sarif
4040
results_format: sarif
@@ -56,6 +56,6 @@ jobs:
5656

5757
# Upload the results to GitHub's code scanning dashboard.
5858
- name: Upload SARIF results to code scanning
59-
uses: github/codeql-action/upload-sarif@9e8d0789d4a0fa9ceb6b1738f7e269594bdd67f0 # v3.28.9
59+
uses: github/codeql-action/upload-sarif@6bb031afdd8eb862ea3fc1848194185e076637e5 # v3.28.11
6060
with:
6161
sarif_file: results.sarif

‎CONTRIBUTING_DOCS.md‎

Lines changed: 30 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -16,14 +16,13 @@ If you're an employee of F5/NGINX, also read [For F5/NGINX Employees](./F5-NGINX
1616
You will need to install Hugo _or_ Docker to build and preview docs in your local development environment.
1717
Refer to the [Hugo installation instructions](https://gohugo.io/getting-started/installing/) for more information.
1818

19-
**NOTE**: We are currently running [Hugo v0.134.2](https://github.com/gohugoio/hugo/releases/tag/v0.134.2) in production.
20-
2119

2220
Although not a strict requirement, markdown-link-check is also used in documentation development.
2321

2422
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.
2523

2624
- [Installing Hugo](https://gohugo.io/getting-started/installing/)
25+
- **NOTE**: We are currently running [Hugo v0.134.2](https://github.com/gohugoio/hugo/releases/tag/v0.134.2) in production.
2726
- [Installing markdownlint-cli](https://github.com/igorshubovych/markdownlint-cli?tab=readme-ov-file#installation)
2827
- [Installing markdown-link-check](https://github.com/tcort/markdown-link-check?tab=readme-ov-file#installation).
2928

@@ -35,7 +34,11 @@ The configuration files are as follows:
3534

3635
## Local Docs Development
3736

38-
To build the documentation locally, use the `make` command in the documentation folder with these targets:
37+
To build the documentation locally, use the `make` command in the documentation folder. First make sure you have the latest version of our Hugo theme with:
38+
39+
`make hugo-update`
40+
41+
Once you've updated the theme, you can use these targets:
3942

4043
```text
4144
make watch - Runs a local Hugo server, allowing for changes to be previewed in a browser.
@@ -64,7 +67,7 @@ We have templates for the following types of documentation:
6467

6568
## How to format docs
6669

67-
### Basic markdown formatting
70+
### Basic Markdown formatting
6871

6972
There are multiple ways to format text: for consistency and clarity, these are our conventions:
7073

@@ -133,12 +136,14 @@ Supported callouts:
133136
- `caution`
134137
- `warning`
135138

136-
You can also create custom callouts using the `call-out` shortcode `{{< call-out "type" "header" "font-awesome icon >}}`. For example:
139+
You can also create custom callouts using the `call-out` shortcode `{{< call-out "type position" "header" "font-awesome icon >}}`. For example:
137140

138141
```md
139-
{{<call-out "important" "JWT file required for upgrade" "fa fa-exclamation-triangle">}}
142+
{{<call-out "important side-callout" "JWT file required for upgrade" "fa fa-exclamation-triangle">}}
140143
```
141144

145+
By default, all custom callouts are included inline, unless you add `side-callout` which places the callout to the right of the content.
146+
142147
Here are some other shortcodes:
143148

144149
- `fa`: Inserts a Font Awesome icon
@@ -152,6 +157,25 @@ Here are some other shortcodes:
152157
- `readfile`: Include the content of another file in the current file, which can be in an arbitrary location.
153158
- `bootstrap-table`: formats a table using Bootstrap classes; accepts any bootstrap table classes as additional arguments, e.g. `{{< bootstrap-table "table-bordered table-hover" }}`
154159

160+
### How to use Hugo includes
161+
162+
As mentioned above, [Hugo includes](https://gohugo.io/contribute/documentation/#include) are a custom shortcode that allows you to reference reusable content stored in the [`/content/includes` directory](https://github.com/nginx/documentation/tree/main/content/includes).
163+
164+
For example, if the [`controller/add-existing-instance.md`](https://github.com/nginx/documentation/blob/main/content/includes/controller/add-existing-instance.md) file contains instructions on adding an instance to the NGINX Controller, you can reuse it on multiple pages by adding:
165+
166+
```md
167+
{{< include "controller/add-existing-instance.md" >}}
168+
```
169+
170+
The `controller/add-existing-instance.md` file is included in the following pages on the NGINX Docs Site:
171+
172+
- [Add an NGINX App Protect Instance](https://github.com/nginx/documentation/blob/main/content/controller/infrastructure/instances/add-nap-instance.md?plain=1#L35)
173+
- [Manage Your NGINX Instances](https://github.com/nginx/documentation/blob/main/content/controller/infrastructure/instances/manage-instances.md?plain=1#L29)
174+
- [Trial NGINX Controller with NGINX Plus](https://github.com/nginx/documentation/blob/main/content/controller/admin-guides/install/try-nginx-controller.md?plain=1#L277)
175+
- [Trial NGINX Controller with App Security](https://github.com/nginx/documentation/blob/main/content/controller/admin-guides/install/try-nginx-controller-app-sec.md?plain=1#L290)
176+
177+
This ensures that content is defined once and referenced in multiple places without duplication.
178+
155179
## Linting
156180

157181
To run the markdownlint check, run the following command, which uses the .markdownlint.yaml file to specify rules. For `<content>`, specify the path to your Markdown files:

‎archetypes/concept.md‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,6 @@ type: concept
1010
# Intended for internal catalogue and search, case sensitive:
1111
# Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit
1212
product:
13-
# Intended for internal catalogue
14-
docs: "DOCS-000"
1513
---
1614

1715
[//]: # "These are Markdown comments to guide you through document structure. Remove them as you go, as well as any unnecessary sections."
@@ -71,4 +69,4 @@ Starting from the <top/left> of the diagram, you can see that <thing> is connect
7169

7270
## See also
7371

74-
[//]: # "Link to related documents, such as concepts, reference material or similar use cases."
72+
[//]: # "Link to related documents, such as concepts, reference material or similar use cases."

‎archetypes/default.md‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,6 @@ type: how-to
1010
# Intended for internal catalogue and search, case sensitive:
1111
# Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit
1212
product:
13-
# Intended for internal catalogue
14-
docs: "DOCS-000"
1513
---
1614

1715
[//]: # "These are Markdown comments to guide you through document structure. Remove them as you go, as well as any unnecessary sections."
@@ -87,4 +85,4 @@ To complete this guide, you will need the following prerequisites:
8785

8886
## See also
8987

90-
[//]: # "Link to related documents, such as concepts, reference material or similar use cases."
88+
[//]: # "Link to related documents, such as concepts, reference material or similar use cases."

‎archetypes/tutorial.md‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,6 @@ type: tutorial
1010
# Intended for internal catalogue and search, case sensitive:
1111
# Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit
1212
product:
13-
# Intended for internal catalogue
14-
docs: "DOCS-000"
1513
---
1614

1715
[//]: # "These are Markdown comments to guide you through document structure. Remove them as you go, as well as any unnecessary sections."
@@ -119,4 +117,4 @@ To verify the creation of <component>, you can also inspect information about it
119117

120118
## See also
121119

122-
[//]: # "Link to related documents, such as concepts, reference material or similar use cases."
120+
[//]: # "Link to related documents, such as concepts, reference material or similar use cases."

0 commit comments

Comments
 (0)