From 804354593910835e84a7ee457e547267d3300ee9 Mon Sep 17 00:00:00 2001 From: Ekaterina Kukushkina Date: Thu, 6 Mar 2025 12:45:16 +0000 Subject: [PATCH 1/8] update public from nginx/documentation --- .gitattributes | 9 ++++++- .../update_from_nginx_documentation.yml | 25 +++++++++++++++++++ 2 files changed, 33 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/update_from_nginx_documentation.yml diff --git a/.gitattributes b/.gitattributes index 4950eb3f9..94e3fee4a 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,4 +1,11 @@ # Set the default behavior for correcting line endings, # in case people don't have core.autocrlf set. * text=auto - +F5-NGINX-team-notes.md merge=ours +README.md merge=ours +LICENSE merge=ours +CONTRIBUTING_DOCS.md merge=ours +CONTRIBUTING.md merge=ours +.github/pull_request_template.md merge=ours +.github/workflows/update_from_nginx_documentation.yml merge=ours +.gitattributes merge=ours diff --git a/.github/workflows/update_from_nginx_documentation.yml b/.github/workflows/update_from_nginx_documentation.yml new file mode 100644 index 000000000..b94f5488c --- /dev/null +++ b/.github/workflows/update_from_nginx_documentation.yml @@ -0,0 +1,25 @@ +name: Sync from nginx/documentaion to public + +on: + workflow_dispatch: + schedule: + - cron: "*/10 * * * *" + +permissions: + contents: write + +jobs: + checkout: + runs-on: ubuntu-latest + if: github.ref == 'refs/heads/main' + + steps: + - name: Update Private + run: | + eval `ssh-agent -s` + echo "${{ secrets.UPDATE_REPO }}" | ssh-add - + git clone https://github.com/nginx/documentation.git + cd documentation + git remote add private git@github.com:nginx/documentation-private.git + git checkout -b public + git push private public From 7e9f3606248befd6cd8cd6b1b75254953291d319 Mon Sep 17 00:00:00 2001 From: Ekaterina Kukushkina Date: Thu, 6 Mar 2025 15:31:41 +0000 Subject: [PATCH 2/8] Updated sync workflow: self link changed to a var. --- .github/workflows/update_from_nginx_documentation.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/update_from_nginx_documentation.yml b/.github/workflows/update_from_nginx_documentation.yml index b94f5488c..4c61849a1 100644 --- a/.github/workflows/update_from_nginx_documentation.yml +++ b/.github/workflows/update_from_nginx_documentation.yml @@ -20,6 +20,6 @@ jobs: echo "${{ secrets.UPDATE_REPO }}" | ssh-add - git clone https://github.com/nginx/documentation.git cd documentation - git remote add private git@github.com:nginx/documentation-private.git + git remote add private git@github.com:${{ github.repository }}.git git checkout -b public git push private public From b67946021138c93719637842839dc0ad99d5f083 Mon Sep 17 00:00:00 2001 From: Ekaterina Kukushkina Date: Thu, 6 Mar 2025 15:35:56 +0000 Subject: [PATCH 3/8] Updated internal version of files. https://github.com/nginxinc/docs-platform/issues/289 --- .github/pull_request_template.md | 44 ++-- CONTRIBUTING.md | 195 ++++++++------ CONTRIBUTING_DOCS.md | 182 -------------- F5-NGINX-team-notes.md | 26 -- LICENSE | 419 +++++++++++++++++++++++++++++-- README.md | 103 ++++++-- 6 files changed, 620 insertions(+), 349 deletions(-) delete mode 100644 CONTRIBUTING_DOCS.md delete mode 100644 F5-NGINX-team-notes.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 113d884bf..e84aa716f 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,35 +1,29 @@ ### Proposed changes -Write a clear and concise description that helps reviewers understand the purpose and impact of your changes. Use the -following format: +Describe the use case and detail of the change. -Problem: Give a brief overview of the problem or feature being addressed. +If this PR addresses an [issue](https://github.com/nginxinc/docs/issues) on GitHub, ensure that you link to it below. -Solution: Explain the approach you took to implement the solution, highlighting any significant design decisions or -considerations. +**GitHub Issue**: +Closes # -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: +### Checklist -Closes #ISSUE +Before creating a PR, run through this checklist and mark each step as complete. -### Checklist +- [ ] I have read the [`CONTRIBUTING`](https://github.com/nginxinc/docs/blob/main/CONTRIBUTING.md) document +- [ ] I have viewed my changes in the documentation Deploy Preview +- [ ] My PR is targeting the correct branch: + - main: content that can be released immediately + - product release branch: content that should be held for a future release +- [ ] I have updated any relevant supporting documentation ([`README.md`](https://github.com/nginxinc/docs/blob/main/README.md) and the [`CHANGELOG.md`](https://github.com/nginxinc/docs/blob/main/CHANGELOG.md)) +- [ ] I have followed the [conventional commits guidelines](https://www.conventionalcommits.org/en/v1.0.0/#summary) for all commits on my branch -Before merging a pull request, run through this checklist and mark each as complete. +When you're ready to merge a PR, run through this checklist and mark each step as complete. -- [ ] 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](https://github.com/nginx/documentation/blob/main/templates/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`](https://github.com/nginx/documentation/blob/main/README.md) and [`CHANGELOG.md`](https://github.com/nginx/documentation/blob/main/CHANGELOG.md) +- [ ] Review the doc for spelling errors. +- [ ] Verify that all links in the doc work. +- [ ] Verify that the doc follows the appropriate content template. +- [ ] Add technical and docs reviewers. Refer to the appropriate CODEOWNERS file, which includes authorized teams of reviewers. +- [ ] Share the PR for review in the [`#nginx-doc-reviews`](https://f5.enterprise.slack.com/archives/C04PYFULN91) channel in Slack. -[^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](https://github.com/nginx/documentation/blob/main/templates/style-guide.md) for guidance about placeholder content. \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 740b54fcf..dcb4101d1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,103 +1,156 @@ -# Contributing guidelines +# Contributing Guidelines -The following is a set of guidelines for community contributions to this -project. We really appreciate your desire to contribute! +The following is a set of guidelines for contributing to this project. We really appreciate that you are considering contributing! -If you are an F5 employee, see the following additional guidance [For F5 Employees](./F5-NGINX-team-notes.md). +## Setup -## Table of contents +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. -- [Report a Bug](#report-a-bug) -- [Suggest a Feature or Enhancement](#suggest-a-feature-or-enhancement) -- [Open a Discussion](#open-a-discussion) -- [Submit a Pull Request](#submit-a-pull-request) - - Review our [Git style guide](#git-style-guide) - - Review our Documentation [style guide](./templates/style-guide.md) - - Review our [Contributing guidelines for writers](./CONTRIBUTING_DOCS.md) -- [Issue Lifecycle](#issue-lifecycle) -- [Content edited elsewhere](#content-edited-elsewhere) -- [F5 Contributor License Agreement (CLA)](#f5-contributor-license-agreement) +**NOTE**: We are currently running [Hugo v0.134.2](https://github.com/gohugoio/hugo/releases/tag/v0.134.2) in production. -## Report a bug -To report a bug, open an issue on GitHub with the label `bug` using the -available bug report issue template. Before reporting a bug, make sure the -issue has not already been reported. +Although not a strict requirement, markdown-link-check is also used in documentation development. -## Suggest a feature or enhancement +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. -To suggest a feature or enhancement, open an issue on GitHub with the label -`feature` or `enhancement` using the available feature request issue template. -Please ensure the feature or enhancement has not already been suggested. +- [Installing Hugo](https://gohugo.io/getting-started/installing/) +- [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). -## Open a Discussion +The configuration files are as follows: -If you want to start a conversation with the community and maintainers, -we encourage you to use -[GitHub Discussions](https://github.com/nginx/documentation/discussions). +- *Hugo*: `config/default/config.toml` +- *markdownlint-cli*: `.markdownlint.json` +- *markdown-link-check* `md-linkcheck-config.json` -## Submit a Pull Request +## Local Docs Development -To contribute to F5 NGINX documentation, follow these steps: +To build the documentation locally, use the `make` command in the documentation folder with these targets: -- Fork the NGINX repository -- Create a branch -- Implement your changes in your branch -- Submit a pull request (PR) when your changes are ready for review +```text +make docs - Builds the documentation. +make watch - Runs a Hugo server to automatically preview changes on a local browser. Use this if you want to preview + the documentation locally before submitting a PR. +make drafts - Runs a Hugo server, and displays documentation marked as drafts on a local browser. By default, drafts + are not displayed. +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. +``` -Alternatively, you're welcome to suggest improvements to highlight problems with -our documentation as described in our [support](./SUPPORT.md) page. +## Add new documentation -### Git style guide +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. -- Keep a clean, concise and meaningful Git commit history on your branch, rebasing locally and squashing before you submit a PR -- Follow the guidelines of writing a good commit message as described here - and summarized in the next few points: +We have templates for the following types of documentation: +- Concept +- Getting started +- How-to guide +- Installation guide +- Reference +- Release notes +- Tutorial - - In the subject line, use the present tense ("Add feature" not "Added feature") - - In the subject line, use the imperative mood ("Move cursor to..." not "Moves cursor to...") - - Limit the subject line to 72 characters or less - - Reference issues and pull requests liberally after the subject line - - Add more detailed description in the body of the git message (`git commit -a` to give you more space and time in - your text editor to write a good message instead of `git commit -am`) +## How to format docs -#### Branch protection rules +### Basic markdown formatting -This repository has the following branch protection rules in place: +There are multiple ways to format text: for consistency and clarity, these are our conventions: -- **Pushing branches that contain the "internal/" prefix is not allowed.** This ensures internal development branches are not accidentally or purposefully pushed to this repo. -- **Two approvers are required for all merges to main and release branches.** This ensures all code that is approved for release to production is appropriately reviewed. This rule applies to all branches with `*release*` in the branch name. -- **Only NGINX DocOps Team members can create release branches.** This ensures the docs team is aware of all branches supporting specific product releases. This rule applies to all branches with `*release*` in the branch name. -- **Pushes (force or otherwise) directly to main or release branches is not allowed.** Release branches serve as "main" for the release they are associated with. Restricting pushes directly to main and release branches ensures all content changes are reviewed and approved. This rule applies to all branches with `*release*` in the branch name and to "main". +- Bold: Two asterisks on each side - `**Bolded text**`. +- Italic: One underscore on each side - `_Italicized text_`. +- Unordered lists: One dash - `- Unordered list item`. +- Ordered lists: The 1 character followed by a stop - `1. Ordered list item`. -### Documentation style guide +> **Note**: The ordered notation automatically enumerates lists when built by Hugo. +Close every section with a horizontal line by using three dashes: `---`. -For detailed guidance, see our documentation [style guide](./templates/style-guide.md). +### How to format internal links -## Issue lifecycle +Internal links should use Hugo [ref and relref shortcodes](https://gohugo.io/content-management/cross-references/). -To ensure a balance between work carried out by the NGINX team while encouraging community involvement on this project, we use the following -issue lifecycle: +- Although file extensions are optional for Hugo, we include them as best practice for page anchors. +- Relative paths are preferred, but just the filename is permissible. +- Paths without a leading forward slash (`/`) are first resolved relative to the current page, then the remainder of the website. -- A new issue is created by a community member -- An owner on the NGINX team is assigned to the issue; this owner shepherds the issue through the subsequent stages in the issue lifecycle -- The owner assigns one or more [labels](https://github.com/nginxinc/oss-docs/issues/labels) to the issue -- The owner, in collaboration with the community member, determines what milestone to attach to an issue. They may be milestones correspond to product releases +Here are two examples: -## Additional NGINX documentation +```md +To install , refer to the [installation instructions]({{< ref "install.md" >}}). +To install , refer to the [integration instructions]({{< relref "/integration/thing.md#section" >}}). +``` -This repository does not include all of the source content for the NGINX documentation. Other relevant repositories include: +### How to add images -- [NGINX Open Source](https://github.com/nginx/nginx) - source for [NGINX changelog](https://nginx.org/en/CHANGES) -- [nginx.org](https://github.com/nginx/nginx.org) - source for https://nginx.org -- [NGINX Unit](https://github.com/nginx/unit) - source for https://unit.nginx.org -- [NGINX Ingress Controller](https://github.com/nginxinc/kubernetes-ingress/) - source for https://docs.nginx.com/nginx-ingress-controller -- [NGINX Agent](https://github.com/nginx/agent) - source for https://docs.nginx.com/nginx-agent +Use the `img` [shortcode](#using-hugo-shortcodes) to add images into your documentation. -In those repositories, you can find documentation source code in the `docs` or `site` subdirectories. +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. -## F5 Contributor License Agreement +> **Note**: The `img` shortcode accepts all of the same parameters as the Hugo [figure shortcode](https://gohugo.io/content-management/shortcodes/#figure). -F5 requires all external contributors to agree to the terms of the F5 CLA (available [here](https://github.com/f5/.github/blob/main/CLA/cla-markdown.md)) before any of their changes can be incorporated into an F5 Open Source repository. +> **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). -If you have not yet agreed to the F5 CLA terms and submit a PR to this repository, a bot will prompt you to view and agree to the F5 CLA. You will have to agree to the F5 CLA terms through a comment in the PR before any of your changes can be merged. Your agreement signature will be safely stored by F5 and no longer be required in future PRs. +### 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. + +For example, to use the `note` callout: + +```md +{{< note >}}Provide the text of the note here.{{< /note >}} +``` + +The callout shortcodes support multi-line blocks: + +```md +{{< 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 >}} +``` + +Supported callouts: +- `note` +- `tip` +- `important` +- `caution` +- `warning` + +You can also create custom callouts using the `call-out` shortcode `{{< call-out "type" "header" "font-awesome icon >}}`. For example: + +```md +{{}} +``` + +Here are some other shortcodes: + +- `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" }}` + +## 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: + +```bash +markdownlint -c .markdownlint.yaml +``` + +> Note: You can run this tool on an entire directory or on an individual file. diff --git a/CONTRIBUTING_DOCS.md b/CONTRIBUTING_DOCS.md deleted file mode 100644 index 2947cc8bd..000000000 --- a/CONTRIBUTING_DOCS.md +++ /dev/null @@ -1,182 +0,0 @@ -# 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. - -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: - -- 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) - -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. - -**NOTE**: We are currently running [Hugo v0.134.2](https://github.com/gohugoio/hugo/releases/tag/v0.134.2) in production. - - -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. - -- [Installing Hugo](https://gohugo.io/getting-started/installing/) -- [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). - -The configuration files are as follows: - -- *Hugo*: `config/default/config.toml` -- *markdownlint-cli*: `.markdownlint.json` -- *markdown-link-check* `md-linkcheck-config.json` - -## Local Docs Development - -To build the documentation locally, use the `make` command in the documentation folder with 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. -``` - -## 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 have templates for the following types of documentation: -- Concept -- Getting started -- How-to guide -- Installation guide -- Reference -- Release notes -- Tutorial - -## How to format docs - -### Basic Markdown formatting - -There are multiple ways to format text: for consistency and clarity, these are our conventions: - -- Bold: Two asterisks on each side - `**Bolded text**`. -- Italic: One underscore on each side - `_Italicized text_`. -- Unordered lists: One dash - `- Unordered list item`. -- 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: `---`. - -### How to format internal links - -Internal links should use Hugo [ref and relref shortcodes](https://gohugo.io/content-management/cross-references/). - -- Although file extensions are optional for Hugo, we include them as best practice for page anchors. -- Relative paths are preferred, but just the filename is permissible. -- Paths without a leading forward slash (`/`) are first resolved relative to the current page, then the remainder of the website. - -Here are two examples: - -```md -To install , refer to the [installation instructions]({{< ref "install.md" >}}). -To install , refer to the [integration instructions]({{< relref "/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. - -For example, to use the `note` callout: - -```md -{{< note >}}Provide the text of the note here.{{< /note >}} -``` - -The callout shortcodes support multi-line blocks: - -```md -{{< 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 >}} -``` - -Supported callouts: -- `note` -- `tip` -- `important` -- `caution` -- `warning` - -You can also create custom callouts using the `call-out` shortcode `{{< call-out "type" "header" "font-awesome icon >}}`. For example: - -```md -{{}} -``` - -Here are some other shortcodes: - -- `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" }}` - -### 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 ``, specify the path to your Markdown files: - -```bash -markdownlint -c .markdownlint.yaml -``` - -> Note: You can run this tool on an entire directory or on an individual file. diff --git a/F5-NGINX-team-notes.md b/F5-NGINX-team-notes.md deleted file mode 100644 index 1b2266d7d..000000000 --- a/F5-NGINX-team-notes.md +++ /dev/null @@ -1,26 +0,0 @@ -# For F5/NGINX Employees - -This repository is a functional mirror. We want to do as much of our work as possible in the -public repository. However, if you are working with: - -- Security content, including personally identifying information (PII). -- Content / features that are not yet ready to be announced. - -Before new content is published at https://docs.nginx.com, it must be written to this `documentation` repository. After you get approvals in the internal `docs` repository, you'll need to create a _second_ pull request in this open `documentation` repository. - -If you are unable to assign yourself as an owner of an issue or a reviewer of a pull request, and are an employee of F5, ask a member of the NGINX documentation team for help. - -We encourage you to work with community contributors. If you participate in -PRs, issues, discussions, and more, follow these guidelines: - -- Follow the [Code of Conduct](./CODE_OF_CONDUCT.md). -- Be helpful. We want to encourage people who contribute to continue. -- Avoid references and links to internal content. -- Do not include information about future releases, changes, or features, unless - specifically authorized. -- Do not include anything that even resembles PII. -- Do not include information that is proprietary to and/or private within F5/NGINX. - -As an F5/NGINX employee, if you have a GitHub account, you should be able to clone these repositories. - -To protect F5/NGINX, the ability to merge pull requests is strictly limited to employees of F5/NGINX. diff --git a/LICENSE b/LICENSE index fe65d66e0..4ea99c213 100644 --- a/LICENSE +++ b/LICENSE @@ -1,24 +1,395 @@ -/* - * Copyright (C) 2025 F5, Inc. - * - * Redistribution and use in source and binary forms, with or without - * modification, are permitted provided that the following conditions - * are met: - * 1. Redistributions of source code must retain the above copyright - * notice, this list of conditions and the following disclaimer. - * 2. Redistributions in binary form must reproduce the above copyright - * notice, this list of conditions and the following disclaimer in the - * documentation and/or other materials provided with the distribution. - * - * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND - * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE - * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS - * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT - * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY - * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - * SUCH DAMAGE. - */ +Attribution 4.0 International + +======================================================================= + +Creative Commons Corporation ("Creative Commons") is not a law firm and +does not provide legal services or legal advice. Distribution of +Creative Commons public licenses does not create a lawyer-client or +other relationship. Creative Commons makes its licenses and related +information available on an "as-is" basis. Creative Commons gives no +warranties regarding its licenses, any material licensed under their +terms and conditions, or any related information. Creative Commons +disclaims all liability for damages resulting from their use to the +fullest extent possible. + +Using Creative Commons Public Licenses + +Creative Commons public licenses provide a standard set of terms and +conditions that creators and other rights holders may use to share +original works of authorship and other material subject to copyright +and certain other rights specified in the public license below. The +following considerations are for informational purposes only, are not +exhaustive, and do not form part of our licenses. + + Considerations for licensors: Our public licenses are + intended for use by those authorized to give the public + permission to use material in ways otherwise restricted by + copyright and certain other rights. Our licenses are + irrevocable. Licensors should read and understand the terms + and conditions of the license they choose before applying it. + Licensors should also secure all rights necessary before + applying our licenses so that the public can reuse the + material as expected. Licensors should clearly mark any + material not subject to the license. This includes other CC- + licensed material, or material used under an exception or + limitation to copyright. More considerations for licensors: + wiki.creativecommons.org/Considerations_for_licensors + + Considerations for the public: By using one of our public + licenses, a licensor grants the public permission to use the + licensed material under specified terms and conditions. If + the licensor's permission is not necessary for any reason--for + example, because of any applicable exception or limitation to + copyright--then that use is not regulated by the license. Our + licenses grant only permissions under copyright and certain + other rights that a licensor has authority to grant. Use of + the licensed material may still be restricted for other + reasons, including because others have copyright or other + rights in the material. A licensor may make special requests, + such as asking that all changes be marked or described. + Although not required by our licenses, you are encouraged to + respect those requests where reasonable. More considerations + for the public: + wiki.creativecommons.org/Considerations_for_licensees + +======================================================================= + +Creative Commons Attribution 4.0 International Public License + +By exercising the Licensed Rights (defined below), You accept and agree +to be bound by the terms and conditions of this Creative Commons +Attribution 4.0 International Public License ("Public License"). To the +extent this Public License may be interpreted as a contract, You are +granted the Licensed Rights in consideration of Your acceptance of +these terms and conditions, and the Licensor grants You such rights in +consideration of benefits the Licensor receives from making the +Licensed Material available under these terms and conditions. + + +Section 1 -- Definitions. + + a. Adapted Material means material subject to Copyright and Similar + Rights that is derived from or based upon the Licensed Material + and in which the Licensed Material is translated, altered, + arranged, transformed, or otherwise modified in a manner requiring + permission under the Copyright and Similar Rights held by the + Licensor. For purposes of this Public License, where the Licensed + Material is a musical work, performance, or sound recording, + Adapted Material is always produced where the Licensed Material is + synched in timed relation with a moving image. + + b. Adapter's License means the license You apply to Your Copyright + and Similar Rights in Your contributions to Adapted Material in + accordance with the terms and conditions of this Public License. + + c. Copyright and Similar Rights means copyright and/or similar rights + closely related to copyright including, without limitation, + performance, broadcast, sound recording, and Sui Generis Database + Rights, without regard to how the rights are labeled or + categorized. For purposes of this Public License, the rights + specified in Section 2(b)(1)-(2) are not Copyright and Similar + Rights. + + d. Effective Technological Measures means those measures that, in the + absence of proper authority, may not be circumvented under laws + fulfilling obligations under Article 11 of the WIPO Copyright + Treaty adopted on December 20, 1996, and/or similar international + agreements. + + e. Exceptions and Limitations means fair use, fair dealing, and/or + any other exception or limitation to Copyright and Similar Rights + that applies to Your use of the Licensed Material. + + f. Licensed Material means the artistic or literary work, database, + or other material to which the Licensor applied this Public + License. + + g. Licensed Rights means the rights granted to You subject to the + terms and conditions of this Public License, which are limited to + all Copyright and Similar Rights that apply to Your use of the + Licensed Material and that the Licensor has authority to license. + + h. Licensor means the individual(s) or entity(ies) granting rights + under this Public License. + + i. Share means to provide material to the public by any means or + process that requires permission under the Licensed Rights, such + as reproduction, public display, public performance, distribution, + dissemination, communication, or importation, and to make material + available to the public including in ways that members of the + public may access the material from a place and at a time + individually chosen by them. + + j. Sui Generis Database Rights means rights other than copyright + resulting from Directive 96/9/EC of the European Parliament and of + the Council of 11 March 1996 on the legal protection of databases, + as amended and/or succeeded, as well as other essentially + equivalent rights anywhere in the world. + + k. You means the individual or entity exercising the Licensed Rights + under this Public License. Your has a corresponding meaning. + + +Section 2 -- Scope. + + a. License grant. + + 1. Subject to the terms and conditions of this Public License, + the Licensor hereby grants You a worldwide, royalty-free, + non-sublicensable, non-exclusive, irrevocable license to + exercise the Licensed Rights in the Licensed Material to: + + a. reproduce and Share the Licensed Material, in whole or + in part; and + + b. produce, reproduce, and Share Adapted Material. + + 2. Exceptions and Limitations. For the avoidance of doubt, where + Exceptions and Limitations apply to Your use, this Public + License does not apply, and You do not need to comply with + its terms and conditions. + + 3. Term. The term of this Public License is specified in Section + 6(a). + + 4. Media and formats; technical modifications allowed. The + Licensor authorizes You to exercise the Licensed Rights in + all media and formats whether now known or hereafter created, + and to make technical modifications necessary to do so. The + Licensor waives and/or agrees not to assert any right or + authority to forbid You from making technical modifications + necessary to exercise the Licensed Rights, including + technical modifications necessary to circumvent Effective + Technological Measures. For purposes of this Public License, + simply making modifications authorized by this Section 2(a) + (4) never produces Adapted Material. + + 5. Downstream recipients. + + a. Offer from the Licensor -- Licensed Material. Every + recipient of the Licensed Material automatically + receives an offer from the Licensor to exercise the + Licensed Rights under the terms and conditions of this + Public License. + + b. No downstream restrictions. You may not offer or impose + any additional or different terms or conditions on, or + apply any Effective Technological Measures to, the + Licensed Material if doing so restricts exercise of the + Licensed Rights by any recipient of the Licensed + Material. + + 6. No endorsement. Nothing in this Public License constitutes or + may be construed as permission to assert or imply that You + are, or that Your use of the Licensed Material is, connected + with, or sponsored, endorsed, or granted official status by, + the Licensor or others designated to receive attribution as + provided in Section 3(a)(1)(A)(i). + + b. Other rights. + + 1. Moral rights, such as the right of integrity, are not + licensed under this Public License, nor are publicity, + privacy, and/or other similar personality rights; however, to + the extent possible, the Licensor waives and/or agrees not to + assert any such rights held by the Licensor to the limited + extent necessary to allow You to exercise the Licensed + Rights, but not otherwise. + + 2. Patent and trademark rights are not licensed under this + Public License. + + 3. To the extent possible, the Licensor waives any right to + collect royalties from You for the exercise of the Licensed + Rights, whether directly or through a collecting society + under any voluntary or waivable statutory or compulsory + licensing scheme. In all other cases the Licensor expressly + reserves any right to collect such royalties. + + +Section 3 -- License Conditions. + +Your exercise of the Licensed Rights is expressly made subject to the +following conditions. + + a. Attribution. + + 1. If You Share the Licensed Material (including in modified + form), You must: + + a. retain the following if it is supplied by the Licensor + with the Licensed Material: + + i. identification of the creator(s) of the Licensed + Material and any others designated to receive + attribution, in any reasonable manner requested by + the Licensor (including by pseudonym if + designated); + + ii. a copyright notice; + + iii. a notice that refers to this Public License; + + iv. a notice that refers to the disclaimer of + warranties; + + v. a URI or hyperlink to the Licensed Material to the + extent reasonably practicable; + + b. indicate if You modified the Licensed Material and + retain an indication of any previous modifications; and + + c. indicate the Licensed Material is licensed under this + Public License, and include the text of, or the URI or + hyperlink to, this Public License. + + 2. You may satisfy the conditions in Section 3(a)(1) in any + reasonable manner based on the medium, means, and context in + which You Share the Licensed Material. For example, it may be + reasonable to satisfy the conditions by providing a URI or + hyperlink to a resource that includes the required + information. + + 3. If requested by the Licensor, You must remove any of the + information required by Section 3(a)(1)(A) to the extent + reasonably practicable. + + 4. If You Share Adapted Material You produce, the Adapter's + License You apply must not prevent recipients of the Adapted + Material from complying with this Public License. + + +Section 4 -- Sui Generis Database Rights. + +Where the Licensed Rights include Sui Generis Database Rights that +apply to Your use of the Licensed Material: + + a. for the avoidance of doubt, Section 2(a)(1) grants You the right + to extract, reuse, reproduce, and Share all or a substantial + portion of the contents of the database; + + b. if You include all or a substantial portion of the database + contents in a database in which You have Sui Generis Database + Rights, then the database in which You have Sui Generis Database + Rights (but not its individual contents) is Adapted Material; and + + c. You must comply with the conditions in Section 3(a) if You Share + all or a substantial portion of the contents of the database. + +For the avoidance of doubt, this Section 4 supplements and does not +replace Your obligations under this Public License where the Licensed +Rights include other Copyright and Similar Rights. + + +Section 5 -- Disclaimer of Warranties and Limitation of Liability. + + a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE + EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS + AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF + ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, + IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, + WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR + PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, + ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT + KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT + ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. + + b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE + TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, + NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, + INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, + COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR + USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN + ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR + DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR + IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. + + c. The disclaimer of warranties and limitation of liability provided + above shall be interpreted in a manner that, to the extent + possible, most closely approximates an absolute disclaimer and + waiver of all liability. + + +Section 6 -- Term and Termination. + + a. This Public License applies for the term of the Copyright and + Similar Rights licensed here. However, if You fail to comply with + this Public License, then Your rights under this Public License + terminate automatically. + + b. Where Your right to use the Licensed Material has terminated under + Section 6(a), it reinstates: + + 1. automatically as of the date the violation is cured, provided + it is cured within 30 days of Your discovery of the + violation; or + + 2. upon express reinstatement by the Licensor. + + For the avoidance of doubt, this Section 6(b) does not affect any + right the Licensor may have to seek remedies for Your violations + of this Public License. + + c. For the avoidance of doubt, the Licensor may also offer the + Licensed Material under separate terms or conditions or stop + distributing the Licensed Material at any time; however, doing so + will not terminate this Public License. + + d. Sections 1, 5, 6, 7, and 8 survive termination of this Public + License. + + +Section 7 -- Other Terms and Conditions. + + a. The Licensor shall not be bound by any additional or different + terms or conditions communicated by You unless expressly agreed. + + b. Any arrangements, understandings, or agreements regarding the + Licensed Material not stated herein are separate from and + independent of the terms and conditions of this Public License. + + +Section 8 -- Interpretation. + + a. For the avoidance of doubt, this Public License does not, and + shall not be interpreted to, reduce, limit, restrict, or impose + conditions on any use of the Licensed Material that could lawfully + be made without permission under this Public License. + + b. To the extent possible, if any provision of this Public License is + deemed unenforceable, it shall be automatically reformed to the + minimum extent necessary to make it enforceable. If the provision + cannot be reformed, it shall be severed from this Public License + without affecting the enforceability of the remaining terms and + conditions. + + c. No term or condition of this Public License will be waived and no + failure to comply consented to unless expressly agreed to by the + Licensor. + + d. Nothing in this Public License constitutes or may be interpreted + as a limitation upon, or waiver of, any privileges and immunities + that apply to the Licensor or You, including from the legal + processes of any jurisdiction or authority. + + +======================================================================= + +Creative Commons is not a party to its public +licenses. Notwithstanding, Creative Commons may elect to apply one of +its public licenses to material it publishes and in those instances +will be considered the “Licensor.” The text of the Creative Commons +public licenses is dedicated to the public domain under the CC0 Public +Domain Dedication. Except for the limited purpose of indicating that +material is shared under a Creative Commons public license or as +otherwise permitted by the Creative Commons policies published at +creativecommons.org/policies, Creative Commons does not authorize the +use of the trademark "Creative Commons" or any other trademark or logo +of Creative Commons without its prior written consent including, +without limitation, in connection with any unauthorized modifications +to any of its public licenses or any other arrangements, +understandings, or agreements concerning use of licensed material. For +the avoidance of doubt, this paragraph does not form part of the +public licenses. + +Creative Commons may be contacted at creativecommons.org. diff --git a/README.md b/README.md index 6143086f8..34105ef76 100644 --- a/README.md +++ b/README.md @@ -1,35 +1,96 @@ -[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/nginxinc/template-repository/badge)](https://securityscorecards.dev/viewer/?uri=github.com/nginxinc/template-repository) -[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) -[![Community Support](https://badgen.net/badge/support/community/cyan?icon=awesome)](https://github.com/nginxinc/template-repository/blob/main/SUPPORT.md) -[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](https://github.com/nginxinc/template-repository/main/CODE_OF_CONDUCT.md) -![Commercial Support](https://badgen.net/badge/support/commercial/green?icon=awesome) +# NGINX Documentation - +[![Check for Broken Links](https://github.com/nginxinc/docs/actions/workflows/check-broken-links.yml/badge.svg)](https://github.com/nginxinc/docs/actions/workflows/check-broken-links.yml) -# NGINX documentation +This repository contains all of the user documentation for NGINX's enterprise products, as well as the requirements for linting, building, and publishing the documentation. -If you want to contribute to [F5 NGINX documentation](https://docs.nginx.com), you've come to the right place. We've organized a series of README-type files to help you get started: +We write our documentation in Markdown. We build it with [Hugo](https://gohugo.io) and our custom [NGINX Hugo theme](https://github.com/nginxinc/nginx-hugo-theme). We set up previews and deployments using our [docs-actions](https://github.com/nginxinc/docs-actions?tab=readme-ov-file#docs-actions) workflow. -- [Contributing](/CONTRIBUTING.md) describes how you can contribute to our documentation. - - [Contributing guidelines for experts](/CONTRIBUTING_DOCS.md) describes how you can contribute (and check your work) with Hugo, our static site generator -- [Code of Conduct](/CODE_OF_CONDUCT.md) describes expectations in the NGINX open source community. -- [License](/LICENSE) shows the license associated with work on this repository. -- [Security](/SECURITY.md) describes the procedures we would like you to follow if you find a security issue. -- [Support](/SUPPORT.md) lists how you can get support as a customer or a community member. +## ✨ Contributing -## Explanation +We are beta-testing contribution using [CloudCannon](https://app.cloudcannon.com). If you would like to participate, send an email to [nginx-doc-ops@f5.com](mailto:nginx-doc-ops@f5.com). -This repository contains user documentation for NGINX's products, as well as the requirements for linting, building, and publishing the documentation. +> Refer to the [CONTRIBUTING](./CONTRIBUTING.md) guide to learn how to develop content using the developer workflow in this repo. -Our documentation is written in Markdown, specifically the [Goldmark](https://github.com/yuin/goldmark) Markdown parser. -We build our docs using [Hugo](https://gohugo.io) and host them in custom URLs on Azure. +--- -## License +## Publishing environments -[BSD 2-Clause "Simplified" License](/LICENSE) +| Development | Staging | Production | +|--------|--------|--------| +| https://docs-dev.nginx.com | https://docs-staging.nginx.com | https://docs.nginx.com | +| All commits to the `dev` branch, feature branches, pull request deploy previews publish to the docs-dev site.

This site is primarily used for review of content under development. | All commits to `staging` publish to the docs-staging environment automatically.

This is helpful for sharing staged content with stakeholders for signoff immediately prior to a release. | Members of the DocOps team can manually publish deploys with a GitHub action.

*Automatic publishing is not currently implemented for this repo.* Work to add a GitHub Action that publishes to the production site once a day is in progress. | -© [F5, Inc.](https://www.f5.com/) 2025 +**NOTE**: Pull request previews and the development and staging sites are all password-protected. You can find the latest login details on Slack or Confluence. +--- + +## Git guidelines + +- Keep a clean, concise and meaningful git commit history on your branch (within reason), rebasing locally and squashing before submitting a PR. +- Use the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) format when writing a commit message, so that changelogs can be automatically generated +- Follow the guidelines of writing a good commit message as described here and summarised in the next few points: + - In the subject line, use the present tense ("Add feature" not "Added feature"). + - In the subject line, use the imperative mood ("Move cursor to..." not "Moves cursor to..."). + - Limit the subject line to 72 characters or less. + - Reference issues and pull requests liberally after the subject line. + - Add more detailed description in the body of the git message (`git commit -a` to give you more space and time in your text editor to write a good message instead of `git commit -am`). + +### Pull requests and forks + +This repo uses a [forking workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow). Take the steps below to fork the repo, check out a feature branch, and open a pull request with your changes. + +1. In the GitHub UI, select the **Fork** button. + + - On the **Create a new fork** page, select the **Owner** (the account where the fork of the repo will be placed). + - Select the **Create fork** button. + +2. If you plan to work on docs in your local development environment, clone your fork. + For example, to clone the repo using SSH, you would run the following command: + + ```shell + git clone git@github.com:/docs.git + ``` + +3. Check out a new feature branch in your fork. This is where you will work on your docs. + + To do this via the command line, you would run the following command: + + ```shell + git checkout -b + ``` + + **CAUTION**: Do not work on the main branch in your fork. This can cause issues when the NGINX Docs team needs to check out your feature branch for editing work. + +4. Make atomic, [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) on your feature branch. + +5. When ready, open a pull request into the **main** branch or a release branch in the **nginxinc/docs** repo. + + - Fill in [our pull request template](https://github.com/nginxinc/docs/blob/main/.github/pull_request_template.md) when opening your PR. + - Tag the appropriate reviewers for your subject area. + Technical reviewers should be able to verify that the information provided is accurate. + Documentation reviewers ensure that the content conforms to the NGINX Style Guide, is grammatically correct, and adheres to the NGINX content templates. + +## Release management and publishing + +**`Main`** is the default branch in this repo. Main should always be releaseable. +**Do not merge any content into main that is not approved for release.** + +If you are working on content that isn't for a specific release (i.e., it can be published upon completion), open your pull request into the `main` branch. + +### Preparing content for future releases + +If you are working on content for a future release, create a release branch from `main` that uses the naming format *acronym-release-x.y.x* (for example, `adm-release-4.0.0`). Work on your docs in feature branches off of the release branch. Open pull requests into the release branch when you are ready to merge your work. + +## Feature requests, support, and issue reporting + +### Report a Bbg + +To report a bug, open an issue on GitHub with the label `bug` using the available bug report issue template. Please ensure the bug has not already been reported. **If the bug is a potential security vulnerability, please report it using our [security policy](https://github.com/nginxinc/docs/blob/main/SECURITY.md).** + +### Suggest a feature or enhancement + +To suggest a feature or enhancement, please create an issue on GitHub with the label `enhancement` using the available [feature request template](https://github.com/nginxinc/docs/blob/main/.github/feature_request_template.md). Please ensure the feature or enhancement has not already been suggested. ## Credits From 310ef070a28fbc2fbc559778ee59c392ee99ff83 Mon Sep 17 00:00:00 2001 From: Ekaterina Kukushkina Date: Thu, 13 Mar 2025 15:50:07 +0000 Subject: [PATCH 4/8] Update .gitattributes --- .gitattributes | 1 - 1 file changed, 1 deletion(-) diff --git a/.gitattributes b/.gitattributes index 94e3fee4a..cfbc70d85 100644 --- a/.gitattributes +++ b/.gitattributes @@ -7,5 +7,4 @@ LICENSE merge=ours CONTRIBUTING_DOCS.md merge=ours CONTRIBUTING.md merge=ours .github/pull_request_template.md merge=ours -.github/workflows/update_from_nginx_documentation.yml merge=ours .gitattributes merge=ours From 0c6cd677ecf704d3e632aef82a67a9cf1a5a5405 Mon Sep 17 00:00:00 2001 From: Ekaterina Kukushkina Date: Thu, 13 Mar 2025 15:58:10 +0000 Subject: [PATCH 5/8] Update .gitattributes fix previous error --- .gitattributes | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/.gitattributes b/.gitattributes index cfbc70d85..3bce338ce 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,10 +1,5 @@ # Set the default behavior for correcting line endings, # in case people don't have core.autocrlf set. * text=auto -F5-NGINX-team-notes.md merge=ours -README.md merge=ours -LICENSE merge=ours -CONTRIBUTING_DOCS.md merge=ours -CONTRIBUTING.md merge=ours -.github/pull_request_template.md merge=ours +.github/workflows/update_from_nginx_documentation.yml merge=ours .gitattributes merge=ours From 64c50550b92028dcc30511d8dc7d43c6f15f49e5 Mon Sep 17 00:00:00 2001 From: Ekaterina Kukushkina Date: Thu, 20 Mar 2025 16:15:55 +0000 Subject: [PATCH 6/8] documentation branch as a mirror of nginx/documentation --- .github/workflows/update_from_nginx_documentation.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/update_from_nginx_documentation.yml b/.github/workflows/update_from_nginx_documentation.yml index 4c61849a1..511c62b58 100644 --- a/.github/workflows/update_from_nginx_documentation.yml +++ b/.github/workflows/update_from_nginx_documentation.yml @@ -21,5 +21,5 @@ jobs: git clone https://github.com/nginx/documentation.git cd documentation git remote add private git@github.com:${{ github.repository }}.git - git checkout -b public - git push private public + git checkout -b documentation + git push private documentation From 332b941ba4e3ec537bd35394002e849faec88cb0 Mon Sep 17 00:00:00 2001 From: Ekaterina Kukushkina Date: Fri, 28 Mar 2025 17:40:22 +0000 Subject: [PATCH 7/8] restore unmerged files --- CONTRIBUTING_DOCS.md | 187 +++++++++++++++++++ LICENSE | 419 +++---------------------------------------- README.md | 103 +++-------- 3 files changed, 232 insertions(+), 477 deletions(-) create mode 100644 CONTRIBUTING_DOCS.md diff --git a/CONTRIBUTING_DOCS.md b/CONTRIBUTING_DOCS.md new file mode 100644 index 000000000..58c264644 --- /dev/null +++ b/CONTRIBUTING_DOCS.md @@ -0,0 +1,187 @@ +# 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. + +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: + +- 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) + +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. + +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). + +The configuration files are as follows: + +- *Hugo*: `config/default/config.toml` +- *markdownlint-cli*: `.markdownlint.json` +- *markdown-link-check* `md-linkcheck-config.json` + +## Local Docs Development + +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: + +`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. +``` + +## 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 have templates for the following types of documentation: +- Concept +- Getting started +- How-to guide +- Installation guide +- Reference +- Release notes +- Tutorial + +## How to format docs + +### Basic Markdown formatting + +There are multiple ways to format text: for consistency and clarity, these are our conventions: + +- Bold: Two asterisks on each side - `**Bolded text**`. +- Italic: One underscore on each side - `_Italicized text_`. +- Unordered lists: One dash - `- Unordered list item`. +- 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: `---`. + +### How to format internal links + +Internal links should use Hugo [ref and relref shortcodes](https://gohugo.io/content-management/cross-references/). + +- Although file extensions are optional for Hugo, we include them as best practice for page anchors. +- Relative paths are preferred, but just the filename is permissible. +- Paths without a leading forward slash (`/`) are first resolved relative to the current page, then the remainder of the website. + +Here are two examples: + +```md +To install , refer to the [installation instructions]({{< ref "install.md" >}}). +To install , refer to the [integration instructions]({{< relref "/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. + +For example, to use the `note` callout: + +```md +{{< note >}}Provide the text of the note here.{{< /note >}} +``` + +The callout shortcodes support multi-line blocks: + +```md +{{< 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 >}} +``` + +Supported callouts: +- `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: + +```md +{{}} +``` + +By default, all custom callouts are included inline, unless you add `side-callout` which places the callout to the right of the content. + +Here are some other shortcodes: + +- `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" }}` + +### 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 ``, specify the path to your Markdown files: + +```bash +markdownlint -c .markdownlint.yaml +``` + +> Note: You can run this tool on an entire directory or on an individual file. diff --git a/LICENSE b/LICENSE index 4ea99c213..fe65d66e0 100644 --- a/LICENSE +++ b/LICENSE @@ -1,395 +1,24 @@ -Attribution 4.0 International - -======================================================================= - -Creative Commons Corporation ("Creative Commons") is not a law firm and -does not provide legal services or legal advice. Distribution of -Creative Commons public licenses does not create a lawyer-client or -other relationship. Creative Commons makes its licenses and related -information available on an "as-is" basis. Creative Commons gives no -warranties regarding its licenses, any material licensed under their -terms and conditions, or any related information. Creative Commons -disclaims all liability for damages resulting from their use to the -fullest extent possible. - -Using Creative Commons Public Licenses - -Creative Commons public licenses provide a standard set of terms and -conditions that creators and other rights holders may use to share -original works of authorship and other material subject to copyright -and certain other rights specified in the public license below. The -following considerations are for informational purposes only, are not -exhaustive, and do not form part of our licenses. - - Considerations for licensors: Our public licenses are - intended for use by those authorized to give the public - permission to use material in ways otherwise restricted by - copyright and certain other rights. Our licenses are - irrevocable. Licensors should read and understand the terms - and conditions of the license they choose before applying it. - Licensors should also secure all rights necessary before - applying our licenses so that the public can reuse the - material as expected. Licensors should clearly mark any - material not subject to the license. This includes other CC- - licensed material, or material used under an exception or - limitation to copyright. More considerations for licensors: - wiki.creativecommons.org/Considerations_for_licensors - - Considerations for the public: By using one of our public - licenses, a licensor grants the public permission to use the - licensed material under specified terms and conditions. If - the licensor's permission is not necessary for any reason--for - example, because of any applicable exception or limitation to - copyright--then that use is not regulated by the license. Our - licenses grant only permissions under copyright and certain - other rights that a licensor has authority to grant. Use of - the licensed material may still be restricted for other - reasons, including because others have copyright or other - rights in the material. A licensor may make special requests, - such as asking that all changes be marked or described. - Although not required by our licenses, you are encouraged to - respect those requests where reasonable. More considerations - for the public: - wiki.creativecommons.org/Considerations_for_licensees - -======================================================================= - -Creative Commons Attribution 4.0 International Public License - -By exercising the Licensed Rights (defined below), You accept and agree -to be bound by the terms and conditions of this Creative Commons -Attribution 4.0 International Public License ("Public License"). To the -extent this Public License may be interpreted as a contract, You are -granted the Licensed Rights in consideration of Your acceptance of -these terms and conditions, and the Licensor grants You such rights in -consideration of benefits the Licensor receives from making the -Licensed Material available under these terms and conditions. - - -Section 1 -- Definitions. - - a. Adapted Material means material subject to Copyright and Similar - Rights that is derived from or based upon the Licensed Material - and in which the Licensed Material is translated, altered, - arranged, transformed, or otherwise modified in a manner requiring - permission under the Copyright and Similar Rights held by the - Licensor. For purposes of this Public License, where the Licensed - Material is a musical work, performance, or sound recording, - Adapted Material is always produced where the Licensed Material is - synched in timed relation with a moving image. - - b. Adapter's License means the license You apply to Your Copyright - and Similar Rights in Your contributions to Adapted Material in - accordance with the terms and conditions of this Public License. - - c. Copyright and Similar Rights means copyright and/or similar rights - closely related to copyright including, without limitation, - performance, broadcast, sound recording, and Sui Generis Database - Rights, without regard to how the rights are labeled or - categorized. For purposes of this Public License, the rights - specified in Section 2(b)(1)-(2) are not Copyright and Similar - Rights. - - d. Effective Technological Measures means those measures that, in the - absence of proper authority, may not be circumvented under laws - fulfilling obligations under Article 11 of the WIPO Copyright - Treaty adopted on December 20, 1996, and/or similar international - agreements. - - e. Exceptions and Limitations means fair use, fair dealing, and/or - any other exception or limitation to Copyright and Similar Rights - that applies to Your use of the Licensed Material. - - f. Licensed Material means the artistic or literary work, database, - or other material to which the Licensor applied this Public - License. - - g. Licensed Rights means the rights granted to You subject to the - terms and conditions of this Public License, which are limited to - all Copyright and Similar Rights that apply to Your use of the - Licensed Material and that the Licensor has authority to license. - - h. Licensor means the individual(s) or entity(ies) granting rights - under this Public License. - - i. Share means to provide material to the public by any means or - process that requires permission under the Licensed Rights, such - as reproduction, public display, public performance, distribution, - dissemination, communication, or importation, and to make material - available to the public including in ways that members of the - public may access the material from a place and at a time - individually chosen by them. - - j. Sui Generis Database Rights means rights other than copyright - resulting from Directive 96/9/EC of the European Parliament and of - the Council of 11 March 1996 on the legal protection of databases, - as amended and/or succeeded, as well as other essentially - equivalent rights anywhere in the world. - - k. You means the individual or entity exercising the Licensed Rights - under this Public License. Your has a corresponding meaning. - - -Section 2 -- Scope. - - a. License grant. - - 1. Subject to the terms and conditions of this Public License, - the Licensor hereby grants You a worldwide, royalty-free, - non-sublicensable, non-exclusive, irrevocable license to - exercise the Licensed Rights in the Licensed Material to: - - a. reproduce and Share the Licensed Material, in whole or - in part; and - - b. produce, reproduce, and Share Adapted Material. - - 2. Exceptions and Limitations. For the avoidance of doubt, where - Exceptions and Limitations apply to Your use, this Public - License does not apply, and You do not need to comply with - its terms and conditions. - - 3. Term. The term of this Public License is specified in Section - 6(a). - - 4. Media and formats; technical modifications allowed. The - Licensor authorizes You to exercise the Licensed Rights in - all media and formats whether now known or hereafter created, - and to make technical modifications necessary to do so. The - Licensor waives and/or agrees not to assert any right or - authority to forbid You from making technical modifications - necessary to exercise the Licensed Rights, including - technical modifications necessary to circumvent Effective - Technological Measures. For purposes of this Public License, - simply making modifications authorized by this Section 2(a) - (4) never produces Adapted Material. - - 5. Downstream recipients. - - a. Offer from the Licensor -- Licensed Material. Every - recipient of the Licensed Material automatically - receives an offer from the Licensor to exercise the - Licensed Rights under the terms and conditions of this - Public License. - - b. No downstream restrictions. You may not offer or impose - any additional or different terms or conditions on, or - apply any Effective Technological Measures to, the - Licensed Material if doing so restricts exercise of the - Licensed Rights by any recipient of the Licensed - Material. - - 6. No endorsement. Nothing in this Public License constitutes or - may be construed as permission to assert or imply that You - are, or that Your use of the Licensed Material is, connected - with, or sponsored, endorsed, or granted official status by, - the Licensor or others designated to receive attribution as - provided in Section 3(a)(1)(A)(i). - - b. Other rights. - - 1. Moral rights, such as the right of integrity, are not - licensed under this Public License, nor are publicity, - privacy, and/or other similar personality rights; however, to - the extent possible, the Licensor waives and/or agrees not to - assert any such rights held by the Licensor to the limited - extent necessary to allow You to exercise the Licensed - Rights, but not otherwise. - - 2. Patent and trademark rights are not licensed under this - Public License. - - 3. To the extent possible, the Licensor waives any right to - collect royalties from You for the exercise of the Licensed - Rights, whether directly or through a collecting society - under any voluntary or waivable statutory or compulsory - licensing scheme. In all other cases the Licensor expressly - reserves any right to collect such royalties. - - -Section 3 -- License Conditions. - -Your exercise of the Licensed Rights is expressly made subject to the -following conditions. - - a. Attribution. - - 1. If You Share the Licensed Material (including in modified - form), You must: - - a. retain the following if it is supplied by the Licensor - with the Licensed Material: - - i. identification of the creator(s) of the Licensed - Material and any others designated to receive - attribution, in any reasonable manner requested by - the Licensor (including by pseudonym if - designated); - - ii. a copyright notice; - - iii. a notice that refers to this Public License; - - iv. a notice that refers to the disclaimer of - warranties; - - v. a URI or hyperlink to the Licensed Material to the - extent reasonably practicable; - - b. indicate if You modified the Licensed Material and - retain an indication of any previous modifications; and - - c. indicate the Licensed Material is licensed under this - Public License, and include the text of, or the URI or - hyperlink to, this Public License. - - 2. You may satisfy the conditions in Section 3(a)(1) in any - reasonable manner based on the medium, means, and context in - which You Share the Licensed Material. For example, it may be - reasonable to satisfy the conditions by providing a URI or - hyperlink to a resource that includes the required - information. - - 3. If requested by the Licensor, You must remove any of the - information required by Section 3(a)(1)(A) to the extent - reasonably practicable. - - 4. If You Share Adapted Material You produce, the Adapter's - License You apply must not prevent recipients of the Adapted - Material from complying with this Public License. - - -Section 4 -- Sui Generis Database Rights. - -Where the Licensed Rights include Sui Generis Database Rights that -apply to Your use of the Licensed Material: - - a. for the avoidance of doubt, Section 2(a)(1) grants You the right - to extract, reuse, reproduce, and Share all or a substantial - portion of the contents of the database; - - b. if You include all or a substantial portion of the database - contents in a database in which You have Sui Generis Database - Rights, then the database in which You have Sui Generis Database - Rights (but not its individual contents) is Adapted Material; and - - c. You must comply with the conditions in Section 3(a) if You Share - all or a substantial portion of the contents of the database. - -For the avoidance of doubt, this Section 4 supplements and does not -replace Your obligations under this Public License where the Licensed -Rights include other Copyright and Similar Rights. - - -Section 5 -- Disclaimer of Warranties and Limitation of Liability. - - a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE - EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS - AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF - ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, - IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, - WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR - PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, - ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT - KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT - ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. - - b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE - TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, - NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, - INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, - COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR - USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN - ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR - DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR - IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. - - c. The disclaimer of warranties and limitation of liability provided - above shall be interpreted in a manner that, to the extent - possible, most closely approximates an absolute disclaimer and - waiver of all liability. - - -Section 6 -- Term and Termination. - - a. This Public License applies for the term of the Copyright and - Similar Rights licensed here. However, if You fail to comply with - this Public License, then Your rights under this Public License - terminate automatically. - - b. Where Your right to use the Licensed Material has terminated under - Section 6(a), it reinstates: - - 1. automatically as of the date the violation is cured, provided - it is cured within 30 days of Your discovery of the - violation; or - - 2. upon express reinstatement by the Licensor. - - For the avoidance of doubt, this Section 6(b) does not affect any - right the Licensor may have to seek remedies for Your violations - of this Public License. - - c. For the avoidance of doubt, the Licensor may also offer the - Licensed Material under separate terms or conditions or stop - distributing the Licensed Material at any time; however, doing so - will not terminate this Public License. - - d. Sections 1, 5, 6, 7, and 8 survive termination of this Public - License. - - -Section 7 -- Other Terms and Conditions. - - a. The Licensor shall not be bound by any additional or different - terms or conditions communicated by You unless expressly agreed. - - b. Any arrangements, understandings, or agreements regarding the - Licensed Material not stated herein are separate from and - independent of the terms and conditions of this Public License. - - -Section 8 -- Interpretation. - - a. For the avoidance of doubt, this Public License does not, and - shall not be interpreted to, reduce, limit, restrict, or impose - conditions on any use of the Licensed Material that could lawfully - be made without permission under this Public License. - - b. To the extent possible, if any provision of this Public License is - deemed unenforceable, it shall be automatically reformed to the - minimum extent necessary to make it enforceable. If the provision - cannot be reformed, it shall be severed from this Public License - without affecting the enforceability of the remaining terms and - conditions. - - c. No term or condition of this Public License will be waived and no - failure to comply consented to unless expressly agreed to by the - Licensor. - - d. Nothing in this Public License constitutes or may be interpreted - as a limitation upon, or waiver of, any privileges and immunities - that apply to the Licensor or You, including from the legal - processes of any jurisdiction or authority. - - -======================================================================= - -Creative Commons is not a party to its public -licenses. Notwithstanding, Creative Commons may elect to apply one of -its public licenses to material it publishes and in those instances -will be considered the “Licensor.” The text of the Creative Commons -public licenses is dedicated to the public domain under the CC0 Public -Domain Dedication. Except for the limited purpose of indicating that -material is shared under a Creative Commons public license or as -otherwise permitted by the Creative Commons policies published at -creativecommons.org/policies, Creative Commons does not authorize the -use of the trademark "Creative Commons" or any other trademark or logo -of Creative Commons without its prior written consent including, -without limitation, in connection with any unauthorized modifications -to any of its public licenses or any other arrangements, -understandings, or agreements concerning use of licensed material. For -the avoidance of doubt, this paragraph does not form part of the -public licenses. - -Creative Commons may be contacted at creativecommons.org. +/* + * Copyright (C) 2025 F5, Inc. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND + * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE + * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL + * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS + * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY + * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + * SUCH DAMAGE. + */ diff --git a/README.md b/README.md index 34105ef76..6143086f8 100644 --- a/README.md +++ b/README.md @@ -1,96 +1,35 @@ -# NGINX Documentation +[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/nginxinc/template-repository/badge)](https://securityscorecards.dev/viewer/?uri=github.com/nginxinc/template-repository) +[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) +[![Community Support](https://badgen.net/badge/support/community/cyan?icon=awesome)](https://github.com/nginxinc/template-repository/blob/main/SUPPORT.md) +[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](https://github.com/nginxinc/template-repository/main/CODE_OF_CONDUCT.md) +![Commercial Support](https://badgen.net/badge/support/commercial/green?icon=awesome) -[![Check for Broken Links](https://github.com/nginxinc/docs/actions/workflows/check-broken-links.yml/badge.svg)](https://github.com/nginxinc/docs/actions/workflows/check-broken-links.yml) + -This repository contains all of the user documentation for NGINX's enterprise products, as well as the requirements for linting, building, and publishing the documentation. +# NGINX documentation -We write our documentation in Markdown. We build it with [Hugo](https://gohugo.io) and our custom [NGINX Hugo theme](https://github.com/nginxinc/nginx-hugo-theme). We set up previews and deployments using our [docs-actions](https://github.com/nginxinc/docs-actions?tab=readme-ov-file#docs-actions) workflow. +If you want to contribute to [F5 NGINX documentation](https://docs.nginx.com), you've come to the right place. We've organized a series of README-type files to help you get started: -## ✨ Contributing +- [Contributing](/CONTRIBUTING.md) describes how you can contribute to our documentation. + - [Contributing guidelines for experts](/CONTRIBUTING_DOCS.md) describes how you can contribute (and check your work) with Hugo, our static site generator +- [Code of Conduct](/CODE_OF_CONDUCT.md) describes expectations in the NGINX open source community. +- [License](/LICENSE) shows the license associated with work on this repository. +- [Security](/SECURITY.md) describes the procedures we would like you to follow if you find a security issue. +- [Support](/SUPPORT.md) lists how you can get support as a customer or a community member. -We are beta-testing contribution using [CloudCannon](https://app.cloudcannon.com). If you would like to participate, send an email to [nginx-doc-ops@f5.com](mailto:nginx-doc-ops@f5.com). +## Explanation -> Refer to the [CONTRIBUTING](./CONTRIBUTING.md) guide to learn how to develop content using the developer workflow in this repo. +This repository contains user documentation for NGINX's products, as well as the requirements for linting, building, and publishing the documentation. ---- +Our documentation is written in Markdown, specifically the [Goldmark](https://github.com/yuin/goldmark) Markdown parser. +We build our docs using [Hugo](https://gohugo.io) and host them in custom URLs on Azure. -## Publishing environments +## License -| Development | Staging | Production | -|--------|--------|--------| -| https://docs-dev.nginx.com | https://docs-staging.nginx.com | https://docs.nginx.com | -| All commits to the `dev` branch, feature branches, pull request deploy previews publish to the docs-dev site.

This site is primarily used for review of content under development. | All commits to `staging` publish to the docs-staging environment automatically.

This is helpful for sharing staged content with stakeholders for signoff immediately prior to a release. | Members of the DocOps team can manually publish deploys with a GitHub action.

*Automatic publishing is not currently implemented for this repo.* Work to add a GitHub Action that publishes to the production site once a day is in progress. | +[BSD 2-Clause "Simplified" License](/LICENSE) -**NOTE**: Pull request previews and the development and staging sites are all password-protected. You can find the latest login details on Slack or Confluence. +© [F5, Inc.](https://www.f5.com/) 2025 ---- - -## Git guidelines - -- Keep a clean, concise and meaningful git commit history on your branch (within reason), rebasing locally and squashing before submitting a PR. -- Use the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) format when writing a commit message, so that changelogs can be automatically generated -- Follow the guidelines of writing a good commit message as described here and summarised in the next few points: - - In the subject line, use the present tense ("Add feature" not "Added feature"). - - In the subject line, use the imperative mood ("Move cursor to..." not "Moves cursor to..."). - - Limit the subject line to 72 characters or less. - - Reference issues and pull requests liberally after the subject line. - - Add more detailed description in the body of the git message (`git commit -a` to give you more space and time in your text editor to write a good message instead of `git commit -am`). - -### Pull requests and forks - -This repo uses a [forking workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow). Take the steps below to fork the repo, check out a feature branch, and open a pull request with your changes. - -1. In the GitHub UI, select the **Fork** button. - - - On the **Create a new fork** page, select the **Owner** (the account where the fork of the repo will be placed). - - Select the **Create fork** button. - -2. If you plan to work on docs in your local development environment, clone your fork. - For example, to clone the repo using SSH, you would run the following command: - - ```shell - git clone git@github.com:/docs.git - ``` - -3. Check out a new feature branch in your fork. This is where you will work on your docs. - - To do this via the command line, you would run the following command: - - ```shell - git checkout -b - ``` - - **CAUTION**: Do not work on the main branch in your fork. This can cause issues when the NGINX Docs team needs to check out your feature branch for editing work. - -4. Make atomic, [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) on your feature branch. - -5. When ready, open a pull request into the **main** branch or a release branch in the **nginxinc/docs** repo. - - - Fill in [our pull request template](https://github.com/nginxinc/docs/blob/main/.github/pull_request_template.md) when opening your PR. - - Tag the appropriate reviewers for your subject area. - Technical reviewers should be able to verify that the information provided is accurate. - Documentation reviewers ensure that the content conforms to the NGINX Style Guide, is grammatically correct, and adheres to the NGINX content templates. - -## Release management and publishing - -**`Main`** is the default branch in this repo. Main should always be releaseable. -**Do not merge any content into main that is not approved for release.** - -If you are working on content that isn't for a specific release (i.e., it can be published upon completion), open your pull request into the `main` branch. - -### Preparing content for future releases - -If you are working on content for a future release, create a release branch from `main` that uses the naming format *acronym-release-x.y.x* (for example, `adm-release-4.0.0`). Work on your docs in feature branches off of the release branch. Open pull requests into the release branch when you are ready to merge your work. - -## Feature requests, support, and issue reporting - -### Report a Bbg - -To report a bug, open an issue on GitHub with the label `bug` using the available bug report issue template. Please ensure the bug has not already been reported. **If the bug is a potential security vulnerability, please report it using our [security policy](https://github.com/nginxinc/docs/blob/main/SECURITY.md).** - -### Suggest a feature or enhancement - -To suggest a feature or enhancement, please create an issue on GitHub with the label `enhancement` using the available [feature request template](https://github.com/nginxinc/docs/blob/main/.github/feature_request_template.md). Please ensure the feature or enhancement has not already been suggested. ## Credits From c1018d4b977a44bd5ee272447e0334b637417fde Mon Sep 17 00:00:00 2001 From: Ekaterina Kukushkina Date: Fri, 28 Mar 2025 17:45:57 +0000 Subject: [PATCH 8/8] super feature --- example.txt | 1 + 1 file changed, 1 insertion(+) create mode 100644 example.txt diff --git a/example.txt b/example.txt new file mode 100644 index 000000000..e6bc82dc4 --- /dev/null +++ b/example.txt @@ -0,0 +1 @@ +some new content