From 63480c2b7cc02f86f6fbe7fd94bb8631f919c55a Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Thu, 17 Apr 2025 16:25:48 +0100 Subject: [PATCH 1/4] feat: Update Contributing guidelines for writers This commit updates the CONTRIBUTING_DOCS.md file to our contemporary standards for documentation formatting, adding mention of Hugo archetypes and our ghcode shortcode, while also removing some slightly redundant information. Certain sentences have been removed or simplified to reduce the amount of contextual reading required: in certain cases, the reader is guided to refer to the style guide for more precise information, such as in the case of using images. There will likely be follow-up work in the future to more cleanly delineate guidance for using Hugo and guidance around writing content in a general sense, to tightly scope the purpose of this document in relation to the style guide. --- CONTRIBUTING_DOCS.md | 110 +++++++++++++++++++++++++------------------ 1 file changed, 65 insertions(+), 45 deletions(-) diff --git a/CONTRIBUTING_DOCS.md b/CONTRIBUTING_DOCS.md index 198b8e3e1..dd5955101 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 From f260ccafffe958290e5f960cc2cd6bfbd9f0491b Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Fri, 18 Apr 2025 09:41:51 +0100 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Travis Martin <33876974+travisamartin@users.noreply.github.com> --- CONTRIBUTING_DOCS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING_DOCS.md b/CONTRIBUTING_DOCS.md index dd5955101..6f1cb558e 100644 --- a/CONTRIBUTING_DOCS.md +++ b/CONTRIBUTING_DOCS.md @@ -92,7 +92,7 @@ Sections can be separated with horizontal lines by using three dashes: `---`. ### How to format internal links -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). +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. @@ -110,7 +110,7 @@ To install , refer to the [integration instructions]({{< ref "/integ 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: From 0e9ccc57591f0726d0061b475d781bee16e2fe92 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Tue, 22 Apr 2025 11:39:15 +0100 Subject: [PATCH 3/4] Update CONTRIBUTING_DOCS.md Co-authored-by: Travis Martin <33876974+travisamartin@users.noreply.github.com> --- CONTRIBUTING_DOCS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING_DOCS.md b/CONTRIBUTING_DOCS.md index 6f1cb558e..cd4bb3065 100644 --- a/CONTRIBUTING_DOCS.md +++ b/CONTRIBUTING_DOCS.md @@ -153,7 +153,7 @@ Here are some other shortcodes: ### Add code to documentation pages -For command, binary and process names, you can use a pair of backticks (\`\\`): ``. +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. From 540e75c6c9821cfcd90d1ef9ce2a2915d6ed8d0d Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Wed, 23 Apr 2025 14:28:32 +0100 Subject: [PATCH 4/4] feat: Update file, incorporating feedback --- CONTRIBUTING_DOCS.md | 61 +++++++++++++++++++++----------------------- 1 file changed, 29 insertions(+), 32 deletions(-) diff --git a/CONTRIBUTING_DOCS.md b/CONTRIBUTING_DOCS.md index cd4bb3065..3fa8270f3 100644 --- a/CONTRIBUTING_DOCS.md +++ b/CONTRIBUTING_DOCS.md @@ -1,29 +1,25 @@ # Contributing guidelines for writers -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. +This page describes our guidelines on using [Hugo](https://gohugo.io/) to write documentation. -Once you add and/or edit our Markdown source files, you can build the content locally as described on this page. -Before you [Submit a Pull Request](#submit-a-pull-request), we recommend that you first: +You will need [git](https://git-scm.com/) to interact with the repository and files: the content itself is written in Markdown. -- Set up our [Static site generator](#setup) - - This will help you [build docs on your local system](#local-docs-development) -- Learn about [Local docs development](#local-docs-development) +Our workflow is to develop content locally, then submit a pull request once we've done our initial draft and editing passes. If you're an employee of F5/NGINX, also read [For F5/NGINX Employees](./F5-NGINX-team-notes.md). ## Setup 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. +Read the [Hugo installation instructions](https://gohugo.io/getting-started/installing/) for more information. 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. - [Installing Hugo](https://gohugo.io/getting-started/installing/) - **NOTE**: We are currently running [Hugo v0.134.2](https://github.com/gohugoio/hugo/releases/tag/v0.134.2) in production. - [Installing markdownlint-cli](https://github.com/igorshubovych/markdownlint-cli?tab=readme-ov-file#installation) -- [Installing markdown-link-check](https://github.com/tcort/markdown-link-check?tab=readme-ov-file#installation). +- [Installing markdown-link-check](https://github.com/tcort/markdown-link-check?tab=readme-ov-file#installation) The configuration files are as follows: @@ -33,28 +29,32 @@ The configuration files are as follows: ## 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: +To build the documentation website locally, use the `make` command in the documentation folder. + +First ensure you have the latest version of the Hugo theme with: `make hugo-update` Once you've updated the theme, you can use these targets: -```text -make watch - Runs a local Hugo server, allowing for changes to be previewed in a browser. -make drafts - Runs a local Hugo server similar to the `watch` target, but displays documents marked with `draft: true` in their metadata. -make docs - Builds the documentation in the local `public/` directory. -make hugo-get - Updates the go module file with the latest version of the theme. -make hugo-tidy - Removes unnecessary dependencies from the go module file. -make hugo-update - Runs the hugo-get and hugo-tidy targets in sequence. -make lint-markdown - Runs [markdownlint](https://github.com/DavidAnson/markdownlint) on the content folder. -make link-check - Runs [markdown-link-check](https://github.com/tcort/markdown-link-check) on all Markdown files. Requires a running instance of Docker. -make clean - Removes the local `public` directory, which is the default output path used by Hugo. -``` +| Target | Description | +| ------------------- | --------------------------------------------------------------------------- | +| _make watch_ | Runs a local Hugo server, allowing for changes to be previewed in a browser. | +| _make drafts_ | Runs a local Hugo server, rendering documents marked with `draft: true` in their metadata.| +| _make docs_ | Builds the documentation in the local `public/` directory. | +| _make clean_ | Removes the local `public` directory | +| _make hugo-get_ | Updates the go module file with the latest version of the theme. | +| _make hugo-tidy_ | Removes unnecessary dependencies from the go module file. | +| _make hugo-update_ | Runs the hugo-get and hugo-tidy targets in sequence. | +| _make lint-markdown_ | Runs [markdownlint](https://github.com/DavidAnson/markdownlint) on the content folder. | +| _make link-check_ | Runs [markdown-link-check](https://github.com/tcort/markdown-link-check) on all Markdown files. | ## Add new documentation We use [Hugo archetypes](https://gohugo.io/content-management/archetypes/) to provide structure for new documentation pages. +Archetypes are how Hugo represents templates for content. + These archetypes include inline advice on Markdown formatting and our most common style guide conventions. To create a new page, run the following command: @@ -86,15 +86,11 @@ There are multiple ways to format text: for consistency and clarity, these are o > **Note**: The ordered notation automatically enumerates lists when built by Hugo. -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 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. +Although file extensions (such as `.md`) are optional for Hugo, we include them for clarity and ease when targeting page anchors. Here are two examples: @@ -153,7 +149,7 @@ Here are some other shortcodes: ### Add code to documentation pages -For command, binary, and process names, you can use a pair of backticks (\`\\`): ``. +For command, binary, and process names, we sparingly use pairs 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. @@ -161,7 +157,8 @@ You can also use the `ghcode` shortcode to embed a single file directly from Git `{{< 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. +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 @@ -199,10 +196,10 @@ View the [Guidelines for includes](/templates/style-guide.md#guidelines-for-incl ## Linting -To run the markdownlint check, run the following command, which uses the .markdownlint.yaml file to specify rules. For ``, specify the path to your Markdown files: +To use markdownlint to check content, run the following command: -```bash -markdownlint -c .markdownlint.yaml +```shell +markdownlint -c .markdownlint.yaml ``` -> Note: You can run this tool on an entire directory or on an individual file. +The content path can be an individual file or a folder.