Merge pull request #15 from nginxinc/doc-build-instructions

Include instructions / code to support hugo builds

.github/CODEOWNERS

@@ -14,18 +14,18 @@
 # Each line is a file pattern followed by one or more owners.
 
 # DocOps
-*                           @nginxinc/nginx-docs
+*                           @nginx/nginx-docs
 # NGINX Plus
-content/nginx/*             @nginxinc/plus-docs-approvers
+content/nginx/*             @nginx/plus-docs-approvers
 # NGINX Agent
-content/nginx/nms/agent/*   @nginxinc/agent-docs-approvers
+content/nginx/nms/agent/*   @nginx/agent-docs-approvers
 # NGINX One
-content/nginx-one/*         @nginxinc/one-docs-approvers
+content/nginx-one/*         @nginx/one-docs-approvers
 # NGINX Instance Manager
-content/nms/nim/*           @nginxinc/nim-docs-approvers
-content/nim/*               @nginxinc/nim-docs-approvers
+content/nms/nim/*           @nginx/nim-docs-approvers
+content/nim/*               @nginx/nim-docs-approvers
 # NGINX App Protect WAF
-content/nap-waf/*           @nginxinc/nap-docs-approvers
-data/nap-waf/*              @nginxinc/nap-docs-approvers
+content/nap-waf/*           @nginx/nap-docs-approvers
+data/nap-waf/*              @nginx/nap-docs-approvers
 # NGINX App Protect DoS
-content/nap-dos/*           @nginxinc/dos-docs-approvers
+content/nap-dos/*           @nginx/dos-docs-approvers

.github/pull_request_template.md

@@ -1,13 +1,34 @@
 ### Proposed changes
 
-Describe the use case and detail of the change. If this PR addresses an issue on GitHub, make sure to include a link to that issue using one of the [supported keywords](https://docs.github.com/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue) in this PR's description or commit message.
+Write a clear and concise description that helps reviewers understand the purpose and impact of your changes. Use the
+following format:
+
+Problem: Give a brief overview of the problem or feature being addressed.
+
+Solution: Explain the approach you took to implement the solution, highlighting any significant design decisions or
+considerations.
+
+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.
+
+Closes #ISSUE
 
 ### Checklist
 
-Before creating a PR, run through this checklist and mark each as complete:
+Before creating a PR, run through this checklist and mark each as complete.
 
 - [ ] I have read the [contributing guidelines](/CONTRIBUTING.md).
 - [ ] I have signed the [F5 Contributor License Agreement (CLA)](https://github.com/f5/.github/blob/main/CLA/cla-markdown.md).
 - [ ] If applicable, I have added tests that prove my fix is effective or that my feature works.
 - [ ] If applicable, I have checked that any relevant tests pass after adding my changes.
 - [ ] I have updated any relevant documentation ([`README.md`](/README.md) and [`CHANGELOG.md`](/CHANGELOG.md)).
+- [ ] I have rebased my branch onto main
+- [ ] I will ensure my PR is targeting the main branch and pulling from my branch from my own fork
+- [ ] If the change involves:
+  - Code
+  - Anything that resembles Personally identifying information (PII)
+  - URLs
+  - Significant new/revised content
+  The change will require at least two (2) approvals before merging. One requirement: use placeholders such as `<JWT Token>` in place of PII

.gitignore

@@ -1,16 +1,45 @@
-# Any private crt and keys #
-############################
-*.crt
-*.key
-*~
-\#*
-
-# OS Specific #
-###############
-Thumbs.db
-.DS_Store
-.vscode
-
-# Logs #
-########
-*.log
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+**/.DS_Store
+
+# dependencies
+
+# testing
+/coverage
+*/test-results
+*/playwright-report
+
+# production
+./public
+
+# misc
+*.pem
+
+# local env files
+.env*.local
+
+# watchdocs
+watchdocs.json
+
+# Local Hugo artifacts
+public/*
+.hugo_build.lock
+resources/
+*.orig
+
+# Local development artifacts
+.markdownlint.json
+**/.vscode/
+**/.idea/
+
+# Local Netlify artifacts
+.netlify/plugins/*
+.netlify/
+
+# Local Lighthouse artifacts
+lighthouse-reports
+
+*.pyc
+build
+*.swp
+*.mo
+node_modules

.markdownlint.yaml

@@ -0,0 +1,42 @@
+default: true
+
+MD002: false
+
+MD003: false
+
+MD004:
+  style: dash
+
+MD009: false
+
+MD010: false
+
+MD012: false
+
+MD013:
+  line_length: 5000
+  heading_line_length: 60
+  code_block_line_length: 80
+  code_blocks: true
+  tables: false
+  headings: true
+  headers: true
+  strict: false
+  stern: false
+
+MD022: false
+
+MD024:
+  siblings_only: true
+
+MD029: false
+
+MD033: false
+
+MD034: false
+
+MD041: false
+
+MD046: false
+
+MD051: false

CONTRIBUTING_DOCS.md

@@ -1,49 +1,165 @@
-# Contributing guidelines for experts
+# Contributing guidelines for writers
 
-If you want to contribute, 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.
+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](#static-site-generator)
-- If you want to add images, review how to [Include images](#include-images)
-- Learn how to [Build documentation locally](#build-documentation-locally)
+- 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)
 
-## Static site generator
+If you're an employee of F5/NGINX, also read [For F5/NGINX Employees](./F5-NGINX-team-notes.md).
 
-You will need to install Hugo to build and preview docs in your local development environment.
+## 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.
+**NOTE**: We are currently running [Hugo v0.134.3](https://github.com/gohugoio/hugo/releases/tag/v0.134.3) in production.
 
-## Include images
 
-When you set up an image, this is the standard format:
+Although not a strict requirement, markdown-link-check is also used in documentation development.
 
-{{< img src="path/to/images/file-name.png" alt="descriptive text for screenreaders" >}}
+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.
 
-You'll find images in the [static](../static) subdirectory, in a directory associated with the documentation. For example, if you've set up the `file-name.png`
-image, you should copy that file to the `static/path/to/images` directory.
+- [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).
 
-## Build documentation locally
+The configuration files are as follows:
 
-To build and preview docs in your local development environment, you need to install Hugo.
-Refer to the [Hugo installation instructions](https://gohugo.io/getting-started/installing/) for more information.
+- *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 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.
+```
+
+## 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 <software>, refer to the [installation instructions]({{< ref "install.md" >}}).
+To install <integation>, 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="<img-file.png>" alt="<Alternative text>">}}`
+   - **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
+{{<call-out "important" "JWT file required for upgrade" "fa fa-exclamation-triangle">}}
+```
 
-## Submit a Pull Request
+Here are some other shortcodes:
 
-Follow this plan to contribute a change to NGINX source code:
+- `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 specifcation 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" }}`
 
-- Fork the NGINX repository
-- Create a branch
-- Implement your changes in this branch
-- Submit a pull request (PR) when your changes are tested and ready for review
+## Linting
 
-### Add new docs
+To run the markdownlint check, run the following command, which uses the .markdownlint.yaml file to specify rules. For `<content>`, specify the path to your Markdown files:
 
-Consistent with the [Diataxis](https://diataxis.fr) framework, our documentation includes the following content types:
+```bash
+markdownlint -c .markdownlint.yaml <content>
+```
 
-- concept: Helps a customer learn about a specific feature or feature set.
-- tutorial: Walks a customer through an example use case scenario; results in a functional PoC environment.
-- reference: Describes an API, command line tool, config options, etc.; should be generated automatically from source code. 
-- openapi: Contains front-matter and shortcode for rendering an openapi.yaml spec.
+> Note: You can run this tool on an entire directory or on an individual file.

F5-NGINX-team-notes.md

@@ -1,7 +1,18 @@
 # For F5/NGINX Employees
 
-This repository is a functional mirror. If you want to make a change to F5/NGINX
-documentation, use the private source repository.
+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.
+
+Make changes to the `docs-internal` repository. When you create a branch, start it with:
+`internal/`. 
+
+- The public `docs` repository will reject branches that start with `internal/`.
+- The `docs-internal` repository will accept branches _only_ if it includes `internal/`.
+
+If you need to review a pull request and are an employee of F5/NGINX, ask a member of @nginx/nginx-docs for help.
 
 We encourage you to work with community contributors. If you participate in
 PRs, issues, discussions, and more, follow these guidelines:
@@ -11,4 +22,7 @@ PRs, issues, discussions, and more, follow these guidelines:
 - Avoid references and links to internal content. 
 - Do not include information about future releases, changes, or features, unless
   specifically authorized.
-- Do not include information that is proprietary to and/or private within F5/NGINX.
+- Do not include anything that even resembles PII.
+- Do not include information that is proprietary to and/or private within F5/NGINX.
+
+To protect F5/NGINX, the ability to merge pull requests is strictly limited to employees of F5/NGINX.