diff --git a/.github/ISSUE_TEMPLATE/1-feature_request.md b/.github/ISSUE_TEMPLATE/1-feature_request.md index a0b4c03f7..8b2820beb 100644 --- a/.github/ISSUE_TEMPLATE/1-feature_request.md +++ b/.github/ISSUE_TEMPLATE/1-feature_request.md @@ -2,7 +2,7 @@ name: Feature request about: Suggest an idea for this project title: "" -labels: "" +labels: "enhancement" assignees: "" --- diff --git a/.github/ISSUE_TEMPLATE/2-bug_report.md b/.github/ISSUE_TEMPLATE/2-bug_report.md index 1d3d925c4..12a6c787b 100644 --- a/.github/ISSUE_TEMPLATE/2-bug_report.md +++ b/.github/ISSUE_TEMPLATE/2-bug_report.md @@ -2,7 +2,7 @@ name: Bug report about: Create a report to help us improve title: "" -labels: "" +labels: "bug" assignees: "" --- diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 113d884bf..47978539f 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -26,10 +26,10 @@ Before merging a pull request, run through this checklist and mark each as compl - [ ] 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) +- [ ] I have ensured that documentation content adheres to [the style guide](/documentation/style-guide.md) - [ ] If the change involves potentially sensitive changes[^1], I have assessed the possible impact - [ ] If applicable, I have added tests that prove my fix is effective or that my feature works - [ ] I have ensured that existing tests pass after adding my changes -- [ ] If applicable, I have updated [`README.md`](https://github.com/nginx/documentation/blob/main/README.md) and [`CHANGELOG.md`](https://github.com/nginx/documentation/blob/main/CHANGELOG.md) +- [ ] If applicable, I have updated [`README.md`](/README.md) -[^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 +[^1]: Potentially sensitive changes include anything involving code, personally identify information (PII), live URLs or significant amounts of new or revised documentation. Please refer to [our style guide](/documentation/style-guide.md) for guidance about placeholder content. \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index b65b17fe4..000000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,5 +0,0 @@ -# Changelog - -## 1.0.0 (January 13, 2025) - -Initial open source release of the documentation repository for enterprise NGINX products. This is a filtered mirror of an internal repository. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dfd79c0d4..7a0af1f48 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,38 +1,36 @@ # Contributing guidelines -The following is a set of guidelines for community contributions to this project. - -We really appreciate your desire to contribute! +The following are a set of guidelines for contributing to this project. We appreciate your desire to get involved! If you are an F5 employee, see the following additional guidance on [Maintainers etiquette](/documentation/maintainers-etiquette.md). ## Table of contents -- [Report a Bug](#report-a-bug) -- [Suggest a Feature or Enhancement](#suggest-a-feature-or-enhancement) -- [Open a Discussion](#open-a-discussion) +- [Create an issue](#create-an-issue) +- [Start a discussion](#start-a-discussion) - [Submit a pull request](#submit-a-pull-request) -- [Issue Lifecycle](#issue-lifecycle) +- [Issue lifecycle](#issue-lifecycle) - [Additional NGINX documentation](#additional-nginx-documentation) - [F5 Contributor License Agreement (CLA)](#f5-contributor-license-agreement) -## Report a bug +## Create an issue + +One way to contribute to the project is by [creating an issue](https://github.com/nginx/documentation/issues/new/choose). + +The two most common are enhancements and bug reports. When using the issue templates, they will be automatically labelled. + +- An enhancement is an improvement of some kind, such as a new document or additional detail for a product feature +- A bug report draws attention to an issue in documentation, such as an incorrect command or outdated information -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. +Before creating an issue, please check there is [no existing issue](https://github.com/nginx/documentation/issues?q=is%3Aissue) for the topic. -## Suggest a feature or enhancement +We encourage discussions within issues, since they act as a source of contextual truth and are linked to pull requests. -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. +## Start a discussion -## Open a Discussion +We encourage you to use [GitHub Discussions](https://github.com/nginx/documentation/discussions) for conversations with the community and maintainers. -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). +If you'd like to discuss something NGINX-related that doesn't involve documentation, you should go to the [NGINX Community Forum](https://community.nginx.org/). ## Submit a pull request @@ -66,7 +64,6 @@ This repository does not include all of the source content for the NGINX documen - [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 In those repositories, you can find documentation source code in the `docs` or `site` subdirectories. diff --git a/README.md b/README.md index 6143086f8..32acb02de 100644 --- a/README.md +++ b/README.md @@ -4,25 +4,21 @@ [![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 +This repository contains the user documentation for NGINX's products, as well as the requirements to build and publish the documentation website. + +Documentation is written in [Markdown](https://daringfireball.net/projects/markdown/basics), then transformed into HTML using the [Hugo](https://gohugo.io/) static site generator. + 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.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. -## Explanation - -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. +You may also find the [documentation folder](/documentation/) for the repository interesting: it's where we store our process information. ## License @@ -30,7 +26,6 @@ We build our docs using [Hugo](https://gohugo.io) and host them in custom URLs o © [F5, Inc.](https://www.f5.com/) 2025 - ## Credits - [The Good Docs Project](https://www.thegooddocsproject.dev/), whose templates we've adapted for our use. diff --git a/documentation/writing-hugo.md b/documentation/writing-hugo.md index 1997a3ad0..00f7d6448 100644 --- a/documentation/writing-hugo.md +++ b/documentation/writing-hugo.md @@ -4,50 +4,35 @@ This page describes our guidelines on using [Hugo](https://gohugo.io/) to write You will need [git](https://git-scm.com/) to interact with the repository and files: the content itself is written in Markdown. -Our workflow is to develop content locally, then submit a pull request once we've done our initial draft and editing passes. +Our workflow is to develop content locally, then [submit a pull request](/documentation/git-conventions.md) once we've done our initial draft and editing passes. For guidance around how to write content, please check [the style guide](/documentation/style-guide.md). ## Setup -You will need to install Hugo _or_ Docker to build and preview docs in your local development environment. +You will need to install Hugo _or_ Docker to build or preview documentation in your local development environment. -Read the [Hugo installation instructions](https://gohugo.io/getting-started/installing/) for more information. +Read the [Hugo installation instructions](https://gohugo.io/getting-started/installing/) for more information: we are currently running [Hugo v0.147.8](https://github.com/gohugoio/hugo/releases/tag/v0.147.8) in production. 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.147.8](https://github.com/gohugoio/hugo/releases/tag/v0.147.8) 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) +## Build the documentation locally -The configuration files are as follows: - -- *Hugo*: `config/default/config.toml` -- *markdownlint-cli*: `.markdownlint.json` -- *markdown-link-check* `md-linkcheck-config.json` - -## Develop documentation locally - -To build the documentation website locally, use the `make` command in the documentation folder. - -First ensure you have the latest version of the Hugo theme with: +To build the website locally, first ensure you have the latest version of the Hugo theme with: `make hugo-update` -Once you've updated the theme, you can use these targets: +You can then use the other `make` commands: *watch* is most commmon when working on documentation. | Target | Description | | ------------------- | --------------------------------------------------------------------------- | | _make watch_ | Runs a local Hugo server, allowing for changes to be previewed in a browser. | | _make drafts_ | Runs a local Hugo server, rendering documents marked with `draft: true` in their metadata.| -| _make docs_ | Builds the documentation in the local `public/` directory. | -| _make clean_ | Removes the local `public` directory | -| _make hugo-get_ | Updates the go module file with the latest version of the theme. | -| _make hugo-tidy_ | Removes unnecessary dependencies from the go module file. | -| _make hugo-update_ | Runs the hugo-get and hugo-tidy targets in sequence. | -| _make lint-markdown_ | Runs [markdownlint](https://github.com/DavidAnson/markdownlint) on the content folder. | -| _make link-check_ | Runs [markdown-link-check](https://github.com/tcort/markdown-link-check) on all Markdown files. | +| _make docs_ | Builds the documentation in the local `public/` directory. | +| _make clean_ | Removes the local `public` directory | +| _make hugo-get_ | Updates the go module file with the latest version of the theme. | +| _make hugo-tidy_ | Removes unnecessary dependencies from the go module file. | +| _make hugo-update_ | Runs the hugo-get and hugo-tidy targets in sequence. | ## Add new documentation @@ -67,9 +52,10 @@ This new page will be created with the default how-to archetype. To use a specif Our archetypes [currently include](/archetypes/) the following: -- `default` (How-to instructions, general use) -- `concept`(An explanation of one implementation detail and some use cases) -- `tutorial` (An in-depth set of how-to instructions, referencing concepts) +- `default` - How-to instructions, general use +- `concept` - An explanation of one implementation detail and some use cases +- `tutorial` - An in-depth set of how-to instructions, referencing concepts +- `landing-page` - A special archetype for the landing page of a documentation set, with a unique layout These archetypes are adapted from some existing [templates](/templates/): please [file an issue](https://github.com/nginx/documentation/issues/new?template=1-feature_request.md) if you would like a new archetype. @@ -165,11 +151,11 @@ An example of this can be seen in [/content/ngf/get-started.md](https://github.c Use the `img` shortcode to add images to documentation pages. It has the same parameters as the Hugo [figure shortcode](https://gohugo.io/content-management/shortcodes/#figure). 1. Add the image to the `/static/img` directory. -1. Add the `img` shortcode: +2. Add the `img` shortcode: - `{{< img src="" alt="">}}` - Do not include a forward slash at the beginning of the file path or it will [break the image](https://gohugo.io/functions/relurl/#input-begins-with-a-slash). -> **Important**: We have strict guidelines for using images. Review them in our [style guide](/templates/style-guide.md#guidelines-for-screenshots). +> **Important**: We have strict guidelines for using images. Review them in our [style guide](/documentation/style-guide.md#guidelines-for-screenshots). ### How to use Hugo includes