diff --git a/CONTRIBUTING_DOCS.md b/CONTRIBUTING_DOCS.md index 198b8e3e..6f1cb558 100644 --- a/CONTRIBUTING_DOCS.md +++ b/CONTRIBUTING_DOCS.md @@ -16,7 +16,6 @@ If you're an employee of F5/NGINX, also read [For F5/NGINX Employees](./F5-NGINX You will need to install Hugo _or_ Docker to build and preview docs in your local development environment. Refer to the [Hugo installation instructions](https://gohugo.io/getting-started/installing/) for more information. - Although not a strict requirement, markdown-link-check is also used in documentation development. 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. @@ -32,7 +31,7 @@ The configuration files are as follows: - *markdownlint-cli*: `.markdownlint.json` - *markdown-link-check* `md-linkcheck-config.json` -## Local Docs Development +## Develop documentation locally 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: @@ -54,18 +53,27 @@ make clean - Removes the local `public` directory, which is the default ## Add new documentation -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. +We use [Hugo archetypes](https://gohugo.io/content-management/archetypes/) to provide structure for new documentation pages. + +These archetypes include inline advice on Markdown formatting and our most common style guide conventions. + +To create a new page, run the following command: + +`hugo new content ` + +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: + +`hugo new content -k ` + +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) -We have templates for the following types of documentation: -- Concept -- Getting started -- How-to guide -- Installation guide -- Reference -- Release notes -- Tutorial +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. -## How to format docs +## How to format documentation ### Basic Markdown formatting @@ -77,39 +85,24 @@ There are multiple ways to format text: for consistency and clarity, these are o - Ordered lists: The 1 character followed by a stop - `1. Ordered list item`. > **Note**: The ordered notation automatically enumerates lists when built by Hugo. -Close every section with a horizontal line by using three dashes: `---`. + +We use backticks sparingly (\`\\`) for `monospace text`, typically for process names or commands. More information is available in the [Add code to documentation pages](#add-code-to-documentation-pages) guidance. + +Sections can be separated with horizontal lines by using three dashes: `---`. ### How to format internal links -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). -Please note that we favor absolute paths, as these are easier to maintain. +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). -- Although file extensions (such as `.md`) are optional for Hugo, we include them as best practice for page anchors. -- We prefer relative paths. -- Paths without a leading forward slash (`/`) are first resolved relative to the current page, then the remainder of the website. +Although file extensions (such as `.md`) are optional for Hugo, we include them as best practice for page anchors. Here are two examples: ```md -To install , refer to the [installation instructions]({{< ref "install.md" >}}). +To install , refer to the [installation instructions]({{< ref "/product/deploy/install.md" >}}). To install , refer to the [integration instructions]({{< ref "/integration/thing.md#section" >}}). ``` -### How to add images - -Use the `img` [shortcode](#using-hugo-shortcodes) to add images into your documentation. - -1. Add the image to the `/static/img` directory. -1. Add the `img` shortcode: - `{{< img src="" alt="">}}` - - **Alt text is required, and must describe in detail the content of the image.** - - **Do not include a forward slash at the beginning of the file path.** - - 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. - -> **Note**: The `img` shortcode accepts all of the same parameters as the Hugo [figure shortcode](https://gohugo.io/content-management/shortcodes/#figure). - -> **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). - ### How to use Hugo shortcodes [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. @@ -117,7 +110,7 @@ Use the `img` [shortcode](#using-hugo-shortcodes) to add images into your docume For example, to use the `note` callout: ```md -{{< note >}}Provide the text of the note here.{{< /note >}} +{{< note >}} Provide the text of the note here .{{< /note >}} ``` The callout shortcodes support multi-line blocks: @@ -143,7 +136,7 @@ You can also create custom callouts using the `call-out` shortcode `{{< call-out {{}} ``` -By default, all custom callouts are included inline, unless you add `side-callout` which places the callout to the right of the content. +By default, all custom callouts are displayed inline, unless you add `side-callout` which places the callout to the right of the content. Here are some other shortcodes: @@ -158,24 +151,51 @@ Here are some other shortcodes: - `readfile`: Include the content of another file in the current file, which can be in an arbitrary location. - `bootstrap-table`: formats a table using Bootstrap classes; accepts any bootstrap table classes as additional arguments, e.g. `{{< bootstrap-table "table-bordered table-hover" }}` +### Add code to documentation pages + +For command, binary and process names, you can use a pair of backticks (\`\\`): ``. + +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. + +You can also use the `ghcode` shortcode to embed a single file directly from GitHub: + +`{{< ghcode "" >}}` + +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. + +### Add images to documentation pages + +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: + - `{{< img src="" alt="">}}` + - 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). + + ### How to use Hugo includes -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). +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). + +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. + +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. -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: +To add it to a documentation page, use the path as a parameter for the `include` shortcode: ```md -{{< include "controller/add-existing-instance.md" >}} +{{< include "licensing-and-reporting/apply-jwt.md" >}} ``` -The `controller/add-existing-instance.md` file is included in the following pages on the NGINX Docs Site: +This particular include file is used in the following pages: -- [Add an NGINX App Protect Instance](https://github.com/nginx/documentation/blob/main/content/controller/infrastructure/instances/add-nap-instance.md?plain=1#L35) -- [Manage Your NGINX Instances](https://github.com/nginx/documentation/blob/main/content/controller/infrastructure/instances/manage-instances.md?plain=1#L29) -- [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) -- [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) +- [About subscription licenses](https://github.com/nginx/documentation/blob/77939c1f9f41ae1984ddfc43c65c3b743836057a/content/solutions/about-subscription-licenses.md?plain=1#L54) +- [R33 pre-release guidance for automatic upgrades](https://github.com/nginx/documentation/blob/77939c1f9f41ae1984ddfc43c65c3b743836057a/content/solutions/r33-pre-release-guidance-for-automatic-upgrades.md?plain=1#L62) +- [Installing NGINX App Protect WAF](https://github.com/nginx/documentation/blob/77939c1f9f41ae1984ddfc43c65c3b743836057a/content/nap-waf/v5/admin-guide/install.md?plain=1#L132) -This ensures that content is defined once and referenced in multiple places without duplication. +View the [Guidelines for includes](/templates/style-guide.md#guidelines-for-includes) for instructions on how to write effective include files. ## Linting