Skip to content

Update CONTRIBUTING_DOCS.md #255

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Mar 5, 2025
Merged

Update CONTRIBUTING_DOCS.md #255

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2efa1f9
Update CONTRIBUTING_DOCS.md
alai97 Mar 4, 2025
c9adffb
Merge branch 'main' into patch-1
ADubhlaoich Mar 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 20 additions & 1 deletion CONTRIBUTING_DOCS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ We have templates for the following types of documentation:

## How to format docs

### Basic markdown formatting
### Basic Markdown formatting

There are multiple ways to format text: for consistency and clarity, these are our conventions:

Expand Down Expand Up @@ -152,6 +152,25 @@ 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" }}`

### 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).

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:

```md
{{< include "controller/add-existing-instance.md" >}}
```

The `controller/add-existing-instance.md` file is included in the following pages on the NGINX Docs Site:

- [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)

This ensures that content is defined once and referenced in multiple places without duplication.

## Linting

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:
Expand Down
Loading