From d54874c883b9dbe9091aeeddf06a3e49ea3fb5df Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Fri, 25 Jul 2025 09:49:36 +0100 Subject: [PATCH] feat: Update Hugo and PR template guidance This commit updates the Hugo guidance to accurately reflect the usage of our most common shortcodes, and guides people away from the ones that have been removed or will be removed soon based on Mainframe changes. The guidance is not fully inclusive: we have not yet determined where full documentation for all theme elements should live (Such as a publicly-facing design system), but it should cover the most commonly used shortcodes. The pull request template has also been updated in the same manner, attempting to focus on critical information for contributors. The checklist was previously quite long: it has been reduced to essential elements, and reframed as a direct, personal commitment. The detail underneath the "Proposed changes" has been shifted to inline, hidden guidance, following a similar pattern in our Hugo archetypes. Some information from the old checklist has been moved there, but it otherwise covers the same ground as the old guidance. It refers to and reinforces our standards asserted by our Git conventions documentation, and will not create visual noise within the PR should the contributor choose not to remove it. --- .github/pull_request_template.md | 43 +++++++---------- documentation/writing-hugo.md | 83 +++++++++++++++----------------- 2 files changed, 56 insertions(+), 70 deletions(-) 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).