diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 47978539f..0432a7bce 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,35 +1,28 @@ ### Proposed changes -Write a clear and concise description that helps reviewers understand the purpose and impact of your changes. Use the -following format: +[//]: # "Write a clear and concise description of what the pull request changes." +[//]: # "You can use our Commit messages guidance for this." +[//]: # "https://github.com/nginx/documentation/blob/main/documentation/git-conventions.md#commit-messages" -Problem: Give a brief overview of the problem or feature being addressed. +[//]: # "First, explain what was changed, and why. This should be most of the detail." +[//]: # "Then how the changes were made, such as referring to existing styles and conventions." +[//]: # "Finish by noting anything beyond the scope of the PR changes that may be affected." -Solution: Explain the approach you took to implement the solution, highlighting any significant design decisions or -considerations. +[//]: # "Include information on testing if relevant and non-obvious from the deployment preview." +[//]: # "For expediency, you can use screenshots to show small before and after examples." -Testing: Describe any testing that you did. - -Please focus on (optional): If you any specific areas where you would like reviewers to focus their attention or provide -specific feedback, add them here. - -If this PR addresses an [issue](https://github.com/nginx/documentation/issues) on GitHub, ensure that you link to it here: - -Closes #ISSUE +[//]: # "If the changes were defined by a GitHub issue, reference it using keywords." +[//]: # "https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests" +[//]: # "DO NOT LINK TO ANY INTERNAL, NON-PUBLIC RESOURCES. THIS INCLUDES BOTH INTERNAL REPOSITORY ISSUES OR ANYTHING IN AN INTRANET." ### Checklist -Before merging a pull request, run through this checklist and mark each as complete. +Before sharing this pull request, I completed the following checklist: -- [ ] I have read the [contributing guidelines](https://github.com/nginx/documentation/blob/main/CONTRIBUTING.md) -- [ ] I have signed the [F5 Contributor License Agreement (CLA)](https://github.com/f5/.github/blob/main/CLA/cla-markdown.md) -- [ ] I have rebased my branch onto main -- [ ] I have ensured my PR is targeting the main branch and pulling from my branch from my own fork -- [ ] I have ensured that the commit messages adhere to [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) -- [ ] I have ensured that documentation content adheres to [the style guide](/documentation/style-guide.md) -- [ ] If the change involves potentially sensitive changes[^1], I have assessed the possible impact -- [ ] If applicable, I have added tests that prove my fix is effective or that my feature works -- [ ] I have ensured that existing tests pass after adding my changes -- [ ] If applicable, I have updated [`README.md`](/README.md) +- [ ] I read the [Contributing guidelines](/CONTRIBUTING.md) +- [ ] My branch adheres to the [Git conventions](/documentation/git-conventions.md) +- [ ] My content changes adhere to the [F5 NGINX Documentation style guide](/documentation/style-guide.md) +- [ ] If my changes involve potentially sensitive information[^1], I have assessed the possible impact +- [ ] I have waited to ensure my changes pass tests, and addressed any discovered issues -[^1]: Potentially sensitive changes include anything involving code, personally identify information (PII), live URLs or significant amounts of new or revised documentation. Please refer to [our style guide](/documentation/style-guide.md) for guidance about placeholder content. \ No newline at end of file +[^1]: Potentially sensitive information includes personally identify information (PII), authentication credentials, and live URLs. Refer to the [style guide](/documentation/style-guide.md) for guidance about placeholder content. \ No newline at end of file diff --git a/documentation/writing-hugo.md b/documentation/writing-hugo.md index 00f7d6448..aab79712a 100644 --- a/documentation/writing-hugo.md +++ b/documentation/writing-hugo.md @@ -87,53 +87,58 @@ To install , refer to the [integration instructions]({{< ref "/integ ### 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. +[Hugo shortcodes](https://github.com/nginxinc/nginx-hugo-theme/tree/main/layouts/shortcodes) are used to provide extra functionality and special formatting to Markdown content. -For example, to use the `note` callout: +This is an example of a call-out shortcode: ```md -{{< note >}} Provide the text of the note here .{{< /note >}} +{{< call-out "note" >}} Provide the text of the note here .{{< /call-out >}} ``` -The callout shortcodes support multi-line blocks: +Here are some other shortcodes: + +- `include`: Include the content of a file in another file: read the [Re-use content with includes](#re-use-content-with-includes) instructions +- `tabs`: Create mutually exclusive tabbed window panes, useful for parallel instructions +- `table`: Add scrollbars to wide tables for browsers with smaller viewports +- `icon`: Add a [Lucide icon](https://lucide.dev/icons/) by using its name as a parameter +- `link`: Link to a file, prepending its path with the Hugo baseUrl +- `ghcode`: Embeds the contents of a code file: read the [Add code to documentation pages](#add-code-to-documentation-pages) instructions +- `openapi`: Loads an OpenAPI specification and render it as HTML using ReDoc + +#### Add call-outs to documentation pages + +The call out shortcode support multi-line blocks: ```md -{{< caution >}} +{{< call-out "caution" >}} You should probably never do this specific thing in a production environment. If you do, and things break, don't say we didn't warn you. -{{< /caution >}} +{{< /call-out >}} ``` -Supported callouts: +The first parameter determines the type of call-out, which defines the colour given to it. + +Supported types: - `note` - `tip` - `important` - `caution` - `warning` -You can also create custom callouts using the `call-out` shortcode `{{< call-out "type position" "header" "font-awesome icon >}}`. For example: +An optional second parameter will add a title to the call-out: without it, it will fall back to the type. ```md -{{}} -``` +{{< call-out "important" "This instruction only applies to v#.#.#" >}} +These instructions are only intended for versions #.#.# onwards. -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: +Follow if you're using an older version. +{{< /call-out >}} +``` -- `fa`: Inserts a Font Awesome icon -- `collapse`: Make a section collapsible -- `tab`: Create mutually exclusive tabbed window panes, useful for parallel instructions -- `table`: Add scrollbars to wide tables for browsers with smaller viewports -- `link`: Link to a file, prepending its path with the Hugo baseUrl -- `openapi`: Loads an OpenAPI specification and render it as HTML using ReDoc -- `include`: Include the content of a file in another file; the included file must be present in the '/content/includes/' directory -- `raw-html`: Include a block of raw HTML -- `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" }}` +Finally, you can use an optional third parameter to add a [Lucide icon](https://lucide.dev/icons/) using its name. -### Add code to documentation pages +#### Add code to documentation pages For command, binary, and process names, we sparingly use pairs of backticks (\`\\`): ``. @@ -145,22 +150,9 @@ You can also use the `ghcode` shortcode to embed a single file directly from Git 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. +#### Re-use content with includes -### 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. -2. 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](/documentation/style-guide.md#guidelines-for-screenshots). - - -### How to use Hugo 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). +The 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. @@ -180,12 +172,13 @@ This particular include file is used in the following pages: View the [Guidelines for includes](/templates/style-guide.md#guidelines-for-includes) for instructions on how to write effective include files. -## Linting +#### Add images to documentation pages -To use markdownlint to check content, run the following command: +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). -```shell -markdownlint -c .markdownlint.yaml -``` +1. Add the image to the `/static/img` directory. +2. 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). -The content path can be an individual file or a folder. +> **Important**: We have strict guidelines for using images. Review them in our [style guide](/documentation/style-guide.md#guidelines-for-screenshots).