From 404fc8393f1cb5ad2a31564b950937a1ca08a5c7 Mon Sep 17 00:00:00 2001 From: Mike Jang Date: Fri, 18 Oct 2024 10:37:58 -0700 Subject: [PATCH] Include instructions / code to support Hugo builds - Include go files to support F5/NGINX Hugo theme - Add files which support `make` for different build types - Set up a compatible code request template --- .github/pull_request_template.md | 19 +++- .gitignore | 58 ++++++++--- .markdownlint.yaml | 42 ++++++++ CONTRIBUTING_DOCS.md | 168 ++++++++++++++++++++++++++----- Makefile | 64 ++++++++++++ config/_default/config.toml | 141 ++++++++++++++++++++++++++ go.mod | 5 + go.sum | 2 + hugo-entrypoint.sh | 4 + 9 files changed, 458 insertions(+), 45 deletions(-) create mode 100644 .markdownlint.yaml create mode 100644 Makefile create mode 100644 config/_default/config.toml create mode 100644 go.mod create mode 100644 go.sum create mode 100755 hugo-entrypoint.sh diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 7661919ba..e23800705 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,13 +1,28 @@ ### 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 diff --git a/.gitignore b/.gitignore index a60260e93..7947422bb 100644 --- a/.gitignore +++ b/.gitignore @@ -1,16 +1,42 @@ -# 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/* +resources/ +*.orig +.hugo_build.lock + +# Local development artifacts +.markdownlint.json +**/.vscode/ +**/.idea/ + +# Local Netlify artifacts +.netlify/plugins/* +.netlify/ + +*.pyc +build +*.swp +*.mo +node_modules diff --git a/.markdownlint.yaml b/.markdownlint.yaml new file mode 100644 index 000000000..8ed0d233d --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/CONTRIBUTING_DOCS.md b/CONTRIBUTING_DOCS.md index bba4e8394..68abb27aa 100644 --- a/CONTRIBUTING_DOCS.md +++ b/CONTRIBUTING_DOCS.md @@ -1,49 +1,163 @@ -# 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 +## Setup -You will need to install Hugo to build and preview docs in your local development environment. +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. -## 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 , 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 +{{}} +``` -## 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 ``, 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 +``` -- 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. diff --git a/Makefile b/Makefile new file mode 100644 index 000000000..28c9379d7 --- /dev/null +++ b/Makefile @@ -0,0 +1,64 @@ +HUGO?=hugo +HUGO_VERSION?=$(shell hugo version 2>/dev/null | awk '{print $$2}' | cut -d '.' -f 2) +HUGO_IMG?=hugomods/hugo:std-go-git-0.134.3 + +THEME_MODULE = github.com/nginxinc/nginx-hugo-theme + +ifeq ($(shell [ $(HUGO_VERSION) -gt 133 2>/dev/null ] && echo true || echo false), true) + $(info Hugo is available and has a version greater than 133. Proceeding with build.) +else + $(warning Hugo is not available or using a version less than 134. Attempting to use docker. HUGO_VERSION=$(HUGO_VERSION)) + HUGO=docker run --rm -it -v ${CURDIR}:/src -p 1313:1313 ${HUGO_IMG} /src/hugo-entrypoint.sh + ifeq (, $(shell docker version 2> /dev/null)) + $(error Hugo (>0.134) or Docker are required to build the local previews.) + endif +endif + +MARKDOWNLINT?=markdownlint +MARKDOWNLINT_IMG?=ghcr.io/igorshubovych/markdownlint-cli:latest + +ifeq (, $(shell ${MARKDOWNLINT} version 2> /dev/null)) +ifeq (, $(shell docker version 2> /dev/null)) +else + MARKDOWNLINT=docker run --rm -i -v ${CURDIR}:/src --workdir /src ${MARKDOWNLINT_IMG} +endif +endif + +MARKDOWNLINKCHECK?=markdown-link-check +MARKDOWNLINKCHECK_IMG?=ghcr.io/tcort/markdown-link-check:stable + +ifeq (, $(shell ${MARKDOWNLINKCHECK} --version 2> /dev/null)) +ifeq (, $(shell docker version 2> /dev/null)) +else + MARKDOWNLINKCHECK=docker run --rm -it -v ${CURDIR}:/docs --workdir /docs ${MARKDOWNLINKCHECK_IMG} +endif +endif + + +.PHONY: docs docs-draft docs-local clean hugo-get hugo-tidy lint-markdown link-check + +docs: + ${HUGO} + +watch: + ${HUGO} --bind 0.0.0.0 -p 1313 server --disableFastRender + +drafts: + ${HUGO} --bind 0.0.0.0 -p 1313 server -D --disableFastRender + +clean: + [ -d "public" ] && rm -rf "public" + +hugo-get: + hugo mod get -u github.com/nginxinc/nginx-hugo-theme + +hugo-tidy: + hugo mod tidy + +hugo-update: hugo-get hugo-tidy + +lint-markdown: + ${MARKDOWNLINT} -c .markdownlint.yaml -- content + +link-check: + ${MARKDOWNLINKCHECK} $(shell find content -name '*.md') diff --git a/config/_default/config.toml b/config/_default/config.toml new file mode 100644 index 000000000..7d0932820 --- /dev/null +++ b/config/_default/config.toml @@ -0,0 +1,141 @@ +baseURL = "/" +languageCode = "en-us" +title = "NGINX Documentation" +refLinksErrorLevel = "ERROR" +pygmentsCodeFences = true +pygmentsUseClasses = true +enableGitInfo = true + +[permalinks] + controller = '/nginx-controller/:sections[1:]/:filename' + modsec-waf = '/nginx-waf/:sections[1:]/:filename' + nap-dos = '/nginx-app-protect-dos/:sections[1:]/:filename' + nap-waf = '/nginx-app-protect-waf/:sections[1:]/:filename' + nms = '/nginx-management-suite/:sections[1:]/:filename' + amplify = '/nginx-amplify/:sections[1:]/:filename' + mesh = '/nginx-service-mesh/:sections[1:]/:filename' + + +[caches] + [caches.modules] + maxAge = -1 + +[module] +[[module.imports]] + path="github.com/nginxinc/nginx-hugo-theme" + +[markup] + [markup.goldmark] + [markup.goldmark.renderer] + unsafe = true + [markup.highlight] + guessSyntax = true + +[params] + useSectionPageLists = "false" + buildtype = "webdocs" + RSSLink = "/index.xml" + author = "NGINX Inc." # add your company name + github = "nginxinc" # add your github profile name + twitter = "@nginx" # add your twitter profile + noindex_kinds = [ + "taxonomy", + "taxonomyTerm" + ] + taxonomiesExcludedFromSitemap = ["tags", "categories", "doctypes"] + + #logo = "" + + # Version lists; used by the versions shortcode + nimvers = [ # list of NIM versions for the versions shortcode + "0.9", + "1.0", + "2.0.0", + "2.0.1", + "2.1.0", + "2.2.0", + "2.3.0", + "2.4.0", + "2.5.0", + "2.6.0", + "2.7.0", + "2.8.0", + "2.9.0" + ] + acmvers = [ # list of ACM versions for the shortcode + "1.0.0", + "1.1.0", + "1.1.1", + "1.2.0", + "1.3.0", + "1.3.1", + "1.4.0", + "1.4.1", + "1.5.0" + ] + + secvers = [ # list of Security Monitoring versions for the shortcode + "1.0.0", + "1.1.0", + "1.2.0", + "1.3.0", + "1.4.0", + "1.5.0", + "1.6.0", + "1.7.0" + ] + + ctrlvers = [ # list of controller versions for the versions shortcode + "3.0", + "3.1", + "3.2", + "3.3", + "3.3", + "3.4", + "3.5", + "3.6", + "3.7", + "3.8", + "3.9", + "3.10", + "3.12", + "3.13", + "3.14", + "3.15", + "3.16.1", + "3.17", + "3.18", + "3.18.1", + "3.18.2", + "3.18.3" + ] + + apimvers = [ # list of Cv3 APIM versions for the versions shortcode + "3.18", + "3.18.1", + "3.19", + "3.19.1", + "3.19.2", + "3.19.3", + "3.19.4", + "3.19.5" + ] + + adcvers = [ # list of Cv3 ADC versions for the versions shortcode + "3.20", + "3.20.1", + "3.21", + "3.22", + "3.22.1", + "3.22.2", + "3.22.3", + "3.22.4", + "3.22.5", + "3.22.6", + "3.22.7", + "3.22.8" + ] + +sectionPagesMenu = "docs" + +ignoreFiles = [ "\\.sh$", "\\.DS_Store$", "\\.git.*$", "\\.txt$", "\\/config\\/.*", "README\\.*"] diff --git a/go.mod b/go.mod new file mode 100644 index 000000000..dee18a98e --- /dev/null +++ b/go.mod @@ -0,0 +1,5 @@ +module github.com/nginxinc/docs + +go 1.19 + +require github.com/nginxinc/nginx-hugo-theme v0.41.22 // indirect diff --git a/go.sum b/go.sum new file mode 100644 index 000000000..1819ea06c --- /dev/null +++ b/go.sum @@ -0,0 +1,2 @@ +github.com/nginxinc/nginx-hugo-theme v0.41.22 h1:Gb/OLbpumNqp8vOPkZzO2GmgPDRd1yr2tWHWUBHg8BA= +github.com/nginxinc/nginx-hugo-theme v0.41.22/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M= diff --git a/hugo-entrypoint.sh b/hugo-entrypoint.sh new file mode 100755 index 000000000..dc7212352 --- /dev/null +++ b/hugo-entrypoint.sh @@ -0,0 +1,4 @@ +#!/bin/sh + +hugo mod get -u github.com/nginxinc/nginx-hugo-theme +hugo $*