|
1 | | -# Contributing guidelines for experts |
| 1 | +# Contributing guidelines for writers |
2 | 2 |
|
3 | | -If you want to contribute, 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 | +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. |
4 | 4 |
|
5 | 5 | Once you add and/or edit our Markdown source files, you can build the content locally as described on this page. |
6 | 6 | Before you [Submit a Pull Request](#submit-a-pull-request), we recommend that you first: |
7 | 7 |
|
8 | | -- Set up our [Static site generator](#static-site-generator) |
9 | | -- If you want to add images, review how to [Include images](#include-images) |
10 | | -- Learn how to [Build documentation locally](#build-documentation-locally) |
| 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) |
11 | 11 |
|
12 | | -## Static site generator |
| 12 | +If you're an employee of F5/NGINX, also read [For F5/NGINX Employees](./F5-NGINX-team-notes.md). |
13 | 13 |
|
14 | | -You will need to install Hugo to build and preview docs in your local development environment. |
| 14 | +## Setup |
| 15 | + |
| 16 | +You will need to install Hugo _or_ Docker to build and preview docs in your local development environment. |
15 | 17 | Refer to the [Hugo installation instructions](https://gohugo.io/getting-started/installing/) for more information. |
16 | 18 |
|
17 | | -**NOTE**: We are currently running [Hugo v0.134.2](https://github.com/gohugoio/hugo/releases/tag/v0.134.2) in production. |
| 19 | +**NOTE**: We are currently running [Hugo v0.134.3](https://github.com/gohugoio/hugo/releases/tag/v0.134.3) in production. |
18 | 20 |
|
19 | | -## Include images |
20 | 21 |
|
21 | | -When you set up an image, this is the standard format: |
| 22 | +Although not a strict requirement, markdown-link-check is also used in documentation development. |
22 | 23 |
|
23 | | -{{< img src="path/to/images/file-name.png" alt="descriptive text for screenreaders" >}} |
| 24 | +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. |
24 | 25 |
|
25 | | -You'll find images in the [static](../static) subdirectory, in a directory associated with the documentation. For example, if you've set up the `file-name.png` |
26 | | -image, you should copy that file to the `static/path/to/images` directory. |
| 26 | +- [Installing Hugo](https://gohugo.io/getting-started/installing/) |
| 27 | +- [Installing markdownlint-cli](https://github.com/igorshubovych/markdownlint-cli?tab=readme-ov-file#installation) |
| 28 | +- [Installing markdown-link-check](https://github.com/tcort/markdown-link-check?tab=readme-ov-file#installation). |
27 | 29 |
|
28 | | -## Build documentation locally |
| 30 | +The configuration files are as follows: |
29 | 31 |
|
30 | | -To build and preview docs in your local development environment, you need to install Hugo. |
31 | | -Refer to the [Hugo installation instructions](https://gohugo.io/getting-started/installing/) for more information. |
| 32 | +- *Hugo*: `config/default/config.toml` |
| 33 | +- *markdownlint-cli*: `.markdownlint.json` |
| 34 | +- *markdown-link-check* `md-linkcheck-config.json` |
| 35 | + |
| 36 | +## Local Docs Development |
| 37 | + |
| 38 | +To build the documentation locally, use the `make` command in the documentation folder with these targets: |
| 39 | + |
| 40 | +```text |
| 41 | +make docs - Builds the documentation. |
| 42 | +make watch - Runs a Hugo server to automatically preview changes on a local browser. Use this if you want to preview |
| 43 | + the documentation locally before submitting a PR. |
| 44 | +make drafts - Runs a Hugo server, and displays documentation marked as drafts on a local browser. By default, drafts |
| 45 | + are not displayed. |
| 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. Requires a running instance of Docker. |
| 51 | +make clean - Removes the local `public` directory, which is the default output path used by Hugo. |
| 52 | +``` |
| 53 | + |
| 54 | +## Add new documentation |
| 55 | + |
| 56 | +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. |
| 57 | + |
| 58 | +We have templates for the following types of documentation: |
| 59 | +- Concept |
| 60 | +- Getting started |
| 61 | +- How-to guide |
| 62 | +- Installation guide |
| 63 | +- Reference |
| 64 | +- Release notes |
| 65 | +- Tutorial |
| 66 | + |
| 67 | +## How to format docs |
| 68 | + |
| 69 | +### Basic markdown formatting |
| 70 | + |
| 71 | +There are multiple ways to format text: for consistency and clarity, these are our conventions: |
| 72 | + |
| 73 | +- Bold: Two asterisks on each side - `**Bolded text**`. |
| 74 | +- Italic: One underscore on each side - `_Italicized text_`. |
| 75 | +- Unordered lists: One dash - `- Unordered list item`. |
| 76 | +- Ordered lists: The 1 character followed by a stop - `1. Ordered list item`. |
| 77 | + |
| 78 | +> **Note**: The ordered notation automatically enumerates lists when built by Hugo. |
| 79 | +Close every section with a horizontal line by using three dashes: `---`. |
| 80 | + |
| 81 | +### How to format internal links |
| 82 | + |
| 83 | +Internal links should use Hugo [ref and relref shortcodes](https://gohugo.io/content-management/cross-references/). |
| 84 | + |
| 85 | +- Although file extensions are optional for Hugo, we include them as best practice for page anchors. |
| 86 | +- Relative paths are preferred, but just the filename is permissible. |
| 87 | +- Paths without a leading forward slash (`/`) are first resolved relative to the current page, then the remainder of the website. |
| 88 | + |
| 89 | +Here are two examples: |
| 90 | + |
| 91 | +```md |
| 92 | +To install <software>, refer to the [installation instructions]({{< ref "install.md" >}}). |
| 93 | +To install <integation>, refer to the [integration instructions]({{< relref "/integration/thing.md#section" >}}). |
| 94 | +``` |
| 95 | + |
| 96 | +### How to add images |
| 97 | + |
| 98 | +Use the `img` [shortcode](#using-hugo-shortcodes) to add images into your documentation. |
| 99 | + |
| 100 | +1. Add the image to the `/static/img` directory. |
| 101 | +1. Add the `img` shortcode: |
| 102 | + `{{< img src="<img-file.png>" alt="<Alternative text>">}}` |
| 103 | + - **Alt text is required, and must describe in detail the content of the image.** |
| 104 | + - **Do not include a forward slash at the beginning of the file path.** |
| 105 | + - 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. |
| 106 | + |
| 107 | +> **Note**: The `img` shortcode accepts all of the same parameters as the Hugo [figure shortcode](https://gohugo.io/content-management/shortcodes/#figure). |
| 108 | +
|
| 109 | +> **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). |
| 110 | +
|
| 111 | +### How to use Hugo shortcodes |
| 112 | + |
| 113 | +[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. |
| 114 | + |
| 115 | +For example, to use the `note` callout: |
| 116 | + |
| 117 | +```md |
| 118 | +{{< note >}}Provide the text of the note here.{{< /note >}} |
| 119 | +``` |
| 120 | + |
| 121 | +The callout shortcodes support multi-line blocks: |
| 122 | + |
| 123 | +```md |
| 124 | +{{< caution >}} |
| 125 | +You should probably never do this specific thing in a production environment. |
| 126 | + |
| 127 | +If you do, and things break, don't say we didn't warn you. |
| 128 | +{{< /caution >}} |
| 129 | +``` |
| 130 | + |
| 131 | +Supported callouts: |
| 132 | +- `note` |
| 133 | +- `tip` |
| 134 | +- `important` |
| 135 | +- `caution` |
| 136 | +- `warning` |
| 137 | + |
| 138 | +You can also create custom callouts using the `call-out` shortcode `{{< call-out "type" "header" "font-awesome icon >}}`. For example: |
| 139 | + |
| 140 | +```md |
| 141 | +{{<call-out "important" "JWT file required for upgrade" "fa fa-exclamation-triangle">}} |
| 142 | +``` |
32 | 143 |
|
33 | | -## Submit a Pull Request |
| 144 | +Here are some other shortcodes: |
34 | 145 |
|
35 | | -Follow this plan to contribute a change to NGINX source code: |
| 146 | +- `fa`: Inserts a Font Awesome icon |
| 147 | +- `collapse`: Make a section collapsible |
| 148 | +- `tab`: Create mutually exclusive tabbed window panes, useful for parallel instructions |
| 149 | +- `table`: Add scrollbars to wide tables for browsers with smaller viewports |
| 150 | +- `link`: Link to a file, prepending its path with the Hugo baseUrl |
| 151 | +- `openapi`: Loads an OpenAPI specifcation and render it as HTML using ReDoc |
| 152 | +- `include`: Include the content of a file in another file; the included file must be present in the '/content/includes/' directory |
| 153 | +- `raw-html`: Include a block of raw HTML |
| 154 | +- `readfile`: Include the content of another file in the current file, which can be in an arbitrary location. |
| 155 | +- `bootstrap-table`: formats a table using Bootstrap classes; accepts any bootstrap table classes as additional arguments, e.g. `{{< bootstrap-table "table-bordered table-hover" }}` |
36 | 156 |
|
37 | | -- Fork the NGINX repository |
38 | | -- Create a branch |
39 | | -- Implement your changes in this branch |
40 | | -- Submit a pull request (PR) when your changes are tested and ready for review |
| 157 | +## Linting |
41 | 158 |
|
42 | | -### Add new docs |
| 159 | +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: |
43 | 160 |
|
44 | | -Consistent with the [Diataxis](https://diataxis.fr) framework, our documentation includes the following content types: |
| 161 | +```bash |
| 162 | +markdownlint -c .markdownlint.yaml <content> |
| 163 | +``` |
45 | 164 |
|
46 | | -- concept: Helps a customer learn about a specific feature or feature set. |
47 | | -- tutorial: Walks a customer through an example use case scenario; results in a functional PoC environment. |
48 | | -- reference: Describes an API, command line tool, config options, etc.; should be generated automatically from source code. |
49 | | -- openapi: Contains front-matter and shortcode for rendering an openapi.yaml spec. |
| 165 | +> Note: You can run this tool on an entire directory or on an individual file. |
0 commit comments