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,47 +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 shortcodes [ref](https://gohugo.io/methods/shortcode/ref/#article) (for absolute paths) and [relref](https://gohugo.io/methods/shortcode/relref/#article) (for relative paths).
85
-
Please note that we favor absolute paths, as these are easier to maintain.
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).
86
92
87
-
- Although file extensions (such as `.md`) are optional for Hugo, we include them as best practice for page anchors.
88
-
- We prefer relative paths.
89
-
- 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.
90
94
91
95
Here are two examples:
92
96
93
97
```md
94
-
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" >}}).
95
99
To install <integation>, refer to the [integration instructions]({{< ref "/integration/thing.md#section" >}}).
96
100
```
97
101
98
-
### How to add images
99
-
100
-
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.**
106
-
-**Do not include a forward slash at the beginning of the file path.**
107
-
- 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.
108
-
109
-
> **Note**: The `img` shortcode accepts all of the same parameters as the Hugo [figure shortcode](https://gohugo.io/content-management/shortcodes/#figure).
110
-
111
-
> **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).
112
-
113
102
### How to use Hugo shortcodes
114
103
115
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.
116
105
117
106
For example, to use the `note` callout:
118
107
119
108
```md
120
-
{{< note >}}Provide the text of the note here.{{< /note >}}
109
+
{{< note >}}Provide the text of the note here.{{< /note >}}
121
110
```
122
111
123
112
The callout shortcodes support multi-line blocks:
@@ -143,7 +132,7 @@ You can also create custom callouts using the `call-out` shortcode `{{< call-out
143
132
{{<call-out "important side-callout" "JWT file required for upgrade" "fa fa-exclamation-triangle">}}
144
133
```
145
134
146
-
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.
147
136
148
137
Here are some other shortcodes:
149
138
@@ -158,31 +147,59 @@ Here are some other shortcodes:
158
147
-`readfile`: Include the content of another file in the current file, which can be in an arbitrary location.
159
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" }}`
160
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
+
161
175
### How to use Hugo includes
162
176
163
-
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.
164
182
165
-
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:
166
184
167
185
```md
168
-
{{< include "controller/add-existing-instance.md" >}}
186
+
{{< include "licensing-and-reporting/apply-jwt.md" >}}
169
187
```
170
188
171
-
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:
172
190
173
-
-[Add an NGINX App Protect Instance](https://github.com/nginx/documentation/blob/main/content/controller/infrastructure/instances/add-nap-instance.md?plain=1#L35)
174
-
-[Manage Your NGINX Instances](https://github.com/nginx/documentation/blob/main/content/controller/infrastructure/instances/manage-instances.md?plain=1#L29)
175
-
-[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)
176
-
-[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.
179
196
180
197
## Linting
181
198
182
-
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:
0 commit comments