You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
If you want to contribute to our content, know Git, and can work from the command line, this page can help you. As noted in the [README](./README.md), we create source content for our documentation in Markdown.
3
+
This page describes our guidelines on using [Hugo](https://gohugo.io/) to write documentation.
4
4
5
-
Once you add and/or edit our Markdown source files, you can build the content locally as described on this page.
6
-
Before you [Submit a Pull Request](#submit-a-pull-request), we recommend that you first:
5
+
You will need [git](https://git-scm.com/) to interact with the repository and files: the content itself is written in Markdown.
7
6
8
-
- Set up our [Static site generator](#setup)
9
-
- This will help you [build docs on your local system](#local-docs-development)
10
-
- Learn about [Local docs development](#local-docs-development)
7
+
Our workflow is to develop content locally, then submit a pull request once we've done our initial draft and editing passes.
11
8
12
9
If you're an employee of F5/NGINX, also read [For F5/NGINX Employees](./F5-NGINX-team-notes.md).
13
10
14
11
## Setup
15
12
16
13
You will need to install Hugo _or_ Docker to build and preview docs in your local development environment.
17
-
Refer to the [Hugo installation instructions](https://gohugo.io/getting-started/installing/) for more information.
18
14
19
-
20
-
Although not a strict requirement, markdown-link-check is also used in documentation development.
15
+
Read the [Hugo installation instructions](https://gohugo.io/getting-started/installing/) for more information.
21
16
22
17
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.
To build the documentation website locally, use the `make` command in the documentation folder.
36
33
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:
34
+
First ensure you have the latest version of the Hugo theme with:
38
35
39
36
`make hugo-update`
40
37
41
38
Once you've updated the theme, you can use these targets:
42
39
43
-
```text
44
-
make watch - Runs a local Hugo server, allowing for changes to be previewed in a browser.
45
-
make drafts - Runs a local Hugo server similar to the `watch` target, but displays documents marked with `draft: true` in their metadata.
46
-
make docs - Builds the documentation in the local `public/` directory.
47
-
make hugo-get - Updates the go module file with the latest version of the theme.
48
-
make hugo-tidy - Removes unnecessary dependencies from the go module file.
49
-
make hugo-update- Runs the hugo-get and hugo-tidy targets in sequence.
50
-
make lint-markdown - Runs [markdownlint](https://github.com/DavidAnson/markdownlint) on the content folder.
51
-
make link-check - Runs [markdown-link-check](https://github.com/tcort/markdown-link-check) on all Markdown files. Requires a running instance of Docker.
52
-
make clean - Removes the local `public` directory, which is the default output path used by Hugo.
|_make watch_|Runs a local Hugo server, allowing for changes to be previewed in a browser. |
43
+
|_make drafts_| Runs a local Hugo server, rendering documents marked with `draft: true` in their metadata.|
44
+
|_make docs_| Builds the documentation in the local `public/` directory. |
45
+
|_make clean_| Removes the local `public` directory |
46
+
|_make hugo-get_| Updates the go module file with the latest version of the theme. |
47
+
|_make hugo-tidy_| Removes unnecessary dependencies from the go module file. |
48
+
|_make hugo-update_|Runs the hugo-get and hugo-tidy targets in sequence. |
49
+
|_make lint-markdown_| Runs [markdownlint](https://github.com/DavidAnson/markdownlint) on the content folder. |
50
+
|_make link-check_| Runs [markdown-link-check](https://github.com/tcort/markdown-link-check) on all Markdown files. |
54
51
55
52
## Add new documentation
56
53
57
-
We provide template files for different types of documentation. The templates, including instructions to use them and examples, are located in the [templates](templates) directory.
54
+
We use [Hugo archetypes](https://gohugo.io/content-management/archetypes/) to provide structure for new documentation pages.
55
+
56
+
Archetypes are how Hugo represents templates for content.
57
+
58
+
These archetypes include inline advice on Markdown formatting and our most common style guide conventions.
59
+
60
+
To create a new page, run the following command:
61
+
62
+
`hugo new content <product/folder/filename.md>`
63
+
64
+
This new page will be created with the default how-to archetype. To use a specific archetype, add the `-k` parameter and its name, such as:
65
+
66
+
`hugo new content <product/folder/filename.md> -k <archetype>`
58
67
59
-
We have templates for the following types of documentation:
60
-
- Concept
61
-
- Getting started
62
-
- How-to guide
63
-
- Installation guide
64
-
- Reference
65
-
- Release notes
66
-
- Tutorial
68
+
Our archetypes [currently include](/archetypes/) the following:
67
69
68
-
## How to format docs
70
+
-`default` (How-to instructions, general use)
71
+
-`concept`(An explanation of one implementation detail and some use cases)
72
+
-`tutorial` (An in-depth set of how-to instructions, referencing concepts)
73
+
74
+
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.
75
+
76
+
## How to format documentation
69
77
70
78
### Basic Markdown formatting
71
79
@@ -77,46 +85,28 @@ There are multiple ways to format text: for consistency and clarity, these are o
77
85
- Ordered lists: The 1 character followed by a stop - `1. Ordered list item`.
78
86
79
87
> **Note**: The ordered notation automatically enumerates lists when built by Hugo.
80
-
Close every section with a horizontal line by using three dashes: `---`.
81
88
82
89
### How to format internal links
83
90
84
-
Internal links should use Hugo[ref and relref shortcodes](https://gohugo.io/content-management/cross-references/).
91
+
Internal links should use the[ref](https://gohugo.io/methods/shortcode/ref/#article) shortcode with absolute paths that start with a forward slash (for clarity).
85
92
86
-
- Although file extensions are optional for Hugo, we include them as best practice for page anchors.
87
-
- Relative paths are preferred, but just the filename is permissible.
88
-
- Paths without a leading forward slash (`/`) are first resolved relative to the current page, then the remainder of the website.
93
+
Although file extensions (such as `.md`) are optional for Hugo, we include them for clarity and ease when targeting page anchors.
89
94
90
95
Here are two examples:
91
96
92
97
```md
93
-
To install <software>, refer to the [installation instructions]({{< ref "install.md" >}}).
98
+
To install <software>, refer to the [installation instructions]({{< ref "/product/deploy/install.md" >}}).
94
99
To install <integation>, refer to the [integration instructions]({{< ref "/integration/thing.md#section" >}}).
95
100
```
96
101
97
-
### How to add images
98
-
99
-
Use the `img`[shortcode](#using-hugo-shortcodes) to add images into your documentation.
-**Alt text is required, and must describe in detail the content of the image.**
105
-
-**Do not include a forward slash at the beginning of the file path.**
106
-
- This will break the image when it's rendered: read about the [Hugo relURL Function](https://gohugo.io/functions/relurl/#input-begins-with-a-slash) to learn more.
107
-
108
-
> **Note**: The `img` shortcode accepts all of the same parameters as the Hugo [figure shortcode](https://gohugo.io/content-management/shortcodes/#figure).
109
-
110
-
> **Important**: We have strict guidelines regarding the use of images in our documentation. Make sure that you keep the number of images to a minimum and that they are relevant to the content. Review the guidelines in our [style guide](/templates/style-guide.md#guidelines-for-screenshots).
111
-
112
102
### How to use Hugo shortcodes
113
103
114
104
[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.
115
105
116
106
For example, to use the `note` callout:
117
107
118
108
```md
119
-
{{< note >}}Provide the text of the note here.{{< /note >}}
109
+
{{< note >}}Provide the text of the note here.{{< /note >}}
120
110
```
121
111
122
112
The callout shortcodes support multi-line blocks:
@@ -142,7 +132,7 @@ You can also create custom callouts using the `call-out` shortcode `{{< call-out
142
132
{{<call-out "important side-callout" "JWT file required for upgrade" "fa fa-exclamation-triangle">}}
143
133
```
144
134
145
-
By default, all custom callouts are included inline, unless you add `side-callout` which places the callout to the right of the content.
135
+
By default, all custom callouts are displayed inline, unless you add `side-callout` which places the callout to the right of the content.
146
136
147
137
Here are some other shortcodes:
148
138
@@ -157,31 +147,59 @@ Here are some other shortcodes:
157
147
-`readfile`: Include the content of another file in the current file, which can be in an arbitrary location.
158
148
-`bootstrap-table`: formats a table using Bootstrap classes; accepts any bootstrap table classes as additional arguments, e.g. `{{< bootstrap-table "table-bordered table-hover" }}`
159
149
150
+
### Add code to documentation pages
151
+
152
+
For command, binary, and process names, we sparingly use pairs of backticks (\`\<some-name\>\`): `<some-name>`.
153
+
154
+
Larger blocks of multi-line code text such as configuration files can be wrapped in triple backticks, with a language as a parameter for highlighted formatting.
155
+
156
+
You can also use the `ghcode` shortcode to embed a single file directly from GitHub:
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.
161
+
162
+
163
+
### Add images to documentation pages
164
+
165
+
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).
- 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).
171
+
172
+
> **Important**: We have strict guidelines for using images. Review them in our [style guide](/templates/style-guide.md#guidelines-for-screenshots).
173
+
174
+
160
175
### How to use Hugo includes
161
176
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).
177
+
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).
178
+
179
+
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
+
181
+
For example, the [`licensing-and-reporting/apply-jwt.md`](https://github.com/nginx/documentation/blob/main/content/includes/licensing-and-reporting/apply-jwt.md) file contains instructions for where to add a JWT license file to an NGINX instance.
163
182
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:
183
+
To add it to a documentation page, use the path as a parameter for the `include` shortcode:
165
184
166
185
```md
167
-
{{< include "controller/add-existing-instance.md" >}}
186
+
{{< include "licensing-and-reporting/apply-jwt.md" >}}
168
187
```
169
188
170
-
The `controller/add-existing-instance.md`file is included in the following pages on the NGINX Docs Site:
189
+
This particular include file is used in the following pages:
171
190
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)
This ensures that content is defined once and referenced in multiple places without duplication.
195
+
View the [Guidelines for includes](/templates/style-guide.md#guidelines-for-includes) for instructions on how to write effective include files.
178
196
179
197
## Linting
180
198
181
-
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:
199
+
To use markdownlint to check content, run the following command:
It takes time to set up NGINX configuration files can take time. Staged Configurations can help. They work like a draft that uses the features of NGINX One Console. The Staged Configuration does not have to be valid.
8
+
It takes time to set up NGINX configuration files. Staged Configurations can help. They work like a draft that uses the features of NGINX One Console. The Staged Configuration does not have to be valid.
9
9
You can save your work before you push a configuration to an instance of NGINX.
10
10
11
11
With Staged Configurations, you can use these features of NGINX One Console:
Copy file name to clipboardExpand all lines: content/includes/nginx-plus/install/configure-usage-reporting.md
+1-2Lines changed: 1 addition & 2 deletions
Original file line number
Diff line number
Diff line change
@@ -2,5 +2,4 @@
2
2
docs:
3
3
---
4
4
5
-
In the `nginx.conf` file, configure license reporting to F5 licensing endpoint using the
6
-
[`mgmt {}`](https://nginx.org/en/docs/ngx_mgmt_module.html) block. By default, no configuration is required. However, it becomes necessary when your NGINX Plus instance is installed in a disconnected environment, uses NGINX Instance manager for usage reporting, or uses a custom path for the license file. For more information, see [About Subscription Licenses]({{< ref "/solutions/about-subscription-licenses.md">}}).
5
+
Make sure license reporting to F5 licensing endpoint is configured. By default, no configuration is required. However, it becomes necessary when NGINX Plus is installed in a disconnected environment, uses NGINX Instance Manager for usage reporting, or uses a custom path for the license file. Configuration can be done in the [`mgmt {}`](https://nginx.org/en/docs/ngx_mgmt_module.html) block of the NGINX Plus configuration file (`/etc/nginx/nginx.conf`). For more information, see [About Subscription Licenses]({{< ref "/solutions/about-subscription-licenses.md">}}).
Copy file name to clipboardExpand all lines: content/includes/nginx-plus/install/copy-crt-and-key.md
+4-4Lines changed: 4 additions & 4 deletions
Original file line number
Diff line number
Diff line change
@@ -2,9 +2,9 @@
2
2
docs:
3
3
---
4
4
5
-
Copy the downloaded **nginx-repo.crt** and **nginx-repo.key** files to the **/etc/ssl/nginx/** directory:
5
+
Copy the downloaded **.crt** and **.key** files to the **/etc/ssl/nginx/** directory and make sure they are named **nginx-repo.crt** and **nginx-repo.key**:
0 commit comments