From 4af54094e964dea9b33499ebae338c789d720d52 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Tue, 3 Sep 2024 16:38:42 +0100 Subject: [PATCH 1/4] Update Makefile and README This commit updates the documentation Makefile and README, reflecting changes to it across NGINX's open source repositories for consistency. It removes unnecessary targets: Netlify is no longer used, nor was the Makefile used for Netlify for quite some time. The guidance for Makefile targets in the README is updated accordingly, as well formatting instructions for how we use Hugo contemporaneously. --- site/Makefile | 67 +++++++++++++++++++++++++++++ site/README.md | 114 ++++++++++++++++++++++++++++--------------------- site/go.sum | 14 ------ site/makefile | 94 ---------------------------------------- 4 files changed, 133 insertions(+), 156 deletions(-) create mode 100644 site/Makefile delete mode 100644 site/makefile diff --git a/site/Makefile b/site/Makefile new file mode 100644 index 0000000000..6b980f1566 --- /dev/null +++ b/site/Makefile @@ -0,0 +1,67 @@ +HUGO?=hugo +HUGO_IMG?=hugomods/hugo:0.115.3 + +THEME_MODULE = github.com/nginxinc/nginx-hugo-theme +THEME_VERSION = 0.41.14 + +ifeq (, $(shell ${HUGO} version 2> /dev/null)) +ifeq (, $(shell docker version 2> /dev/null)) + $(error Docker and Hugo are not installed. Hugo (<0.91) or Docker are required to build the local preview.) +else + HUGO=docker run --rm -it -v ${CURDIR}:/src -p 1313:1313 ${HUGO_IMG} hugo --bind 0.0.0.0 -p 1313 +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)) +ifneq (, $(shell $(NETLIFY) "true")) + $(error Docker and markdownlint are not installed. markdownlint or Docker are required to lint.) +endif +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)) +ifneq (, $(shell $(NETLIFY) "true")) + $(error Docker and markdown-link-check are not installed. markdown-link-check or Docker are required to check links.) +endif +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 $(THEME_MODULE)@v$(THEME_VERSION) + +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') \ No newline at end of file diff --git a/site/README.md b/site/README.md index 4b313bd1af..0e771c2deb 100644 --- a/site/README.md +++ b/site/README.md @@ -1,14 +1,14 @@ -# NGINX Agent Docs +# NGINX Agent Documentation This directory contains all of the user documentation for NGINX Agent, as well as the requirements for linting, building, and publishing the documentation. -Docs are written in Markdown. We build the docs using [Hugo](https://gohugo.io). Previews and deployments are handled by the [docs-actions](https://github.com/nginxinc/docs-actions?tab=readme-ov-file#docs-actions) workflow. +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. ## Setup 1. To install Hugo locally, refer to the [Hugo installation instructions](https://gohugo.io/getting-started/installing/). - > **NOTE**: We are currently running [Hugo v0.115.3](https://github.com/gohugoio/hugo/releases/tag/v0.115.3) in production. + > **Note**: We currently use [Hugo v0.115.3](https://github.com/gohugoio/hugo/releases/tag/v0.115.3) in production. 2. We use markdownlint to check that Markdown files are correct. Use `npm` to install markdownlint-cli: @@ -16,32 +16,37 @@ Docs are written in Markdown. We build the docs using [Hugo](https://gohugo.io). npm install -g markdownlint-cli ``` -## Local Docs Development +## Develop documentation locally -To build the docs locally, run the desired `make` command from the docs directory: +To build the docs locally, use the `make` command in the documentation folder with these targets: ```text -make clean - removes the local `public` directory, which is the default output path used by Hugo -make docs - runs a local hugo server so you can view docs in your browser while you work -make hugo-mod - cleans the Hugo module cache and fetches the latest version of the theme module -make docs-drafts - runs the local hugo server and includes all docs marked with `draft: true` +make docs - Builds the documentation +make watch - Runs a local Hugo server to automatically preview changes +make drafts - Runs a local Hugo server, and displays documentation marked as drafts +make clean - Removes the output 'public' directory created by Hugo +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 on the content folder +make link-check - Runs markdown-link-check on all Markdown files ``` ## Linting -- To run the markdownlint check, run the following command from the docs directory: +- To use markdownlint, use the following command in the documentation directory: ```bash markdownlint -c docs/mdlint_conf.json content ``` - Note: You can run this tool on an entire directory or on an individual file. + > **Note**: You can run this tool on an entire directory or on an individual file. -## Add new docs +## Add new documentation -### Generate a new doc file using Hugo +### Generate a new documentation file using Hugo -To create a new doc file that contains all of the pre-configured Hugo front-matter and the docs task template, **run the following command in the docs directory**: +To create a new documentation file containing the pre-configured Hugo front-matter with the task template, **run the following command in the documentation directory**: `hugo new /.` @@ -51,7 +56,7 @@ For example: hugo new getting-started/install.md ``` -The default template -- task -- should be used for most docs. To create docs using the other content templates, you can use the `--kind` flag: +The default template -- task -- should be used for most documentation. To create documentation using the other content templates, you can use the `--kind` flag: ```shell hugo new tutorials/deploy.md --kind tutorial @@ -65,52 +70,63 @@ The available content types (`kind`) are: - troubleshooting: Helps a customer solve a specific problem. - openapi: Contains front-matter and shortcode for rendering an openapi.yaml spec -## How to format docs +## Documentation formatting -### How to format internal links +### Basic markdown formatting -Format links as [Hugo refs](https://gohugo.io/content-management/cross-references/). +There are multiple ways to format text: for consistency and clarity, these are our conventions: -- File extensions are optional. -- You can use relative paths or just the filename. (**Paths without a leading / are first resolved relative to the current page, then to the remainder of the site.**) -- Anchors are supported. +- 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`. -For example: +> **Note**: The ordered notation automatically enumerates lists when built by Hugo. -```md -To install , refer to the [installation instructions]({{< ref "install" >}}). -``` +Close every section with a horizontal line by using three dashes: `---`. + +### How to format internal links -### How to include images +Internal links should use Hugo [ref and relref shortcodes](https://gohugo.io/content-management/cross-references/). -You can use the `img` [shortcode](#how-to-use-hugo-shortcodes) to add images into your documentation. +- 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. -1. Add the image to the static/img directory, or to the same directory as the doc you want to use it in. +Here are two examples: - - **DO NOT include a forward slash at the beginning of the file path.** This will break the image when it's rendered. - See the docs for the [Hugo relURL Function](https://gohugo.io/functions/relurl/#input-begins-with-a-slash) to learn more. +```md +To install , refer to the [installation instructions]({{< ref "install.md" >}}). +To install , refer to the [integration instructions]({{< relref "/integration/thing.md#section" >}}). +``` -1. Add the img shortcode: +### How to add images - {{< img src="" >}} +Use the `img` [shortcode](#using-hugo-shortcodes) to add images into your documentation. -> Note: The shortcode accepts all of 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: + `{{< img src="" >}}` + - **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. -### How to use Hugo shortcodes +> **Note**: The `img` shortcode accepts all of the same parameters as the Hugo [figure shortcode](https://gohugo.io/content-management/shortcodes/#figure). -You can use [Hugo shortcodes](/docs/themes/f5-hugo/layouts/shortcodes/) to do things like format callouts, add images, and reuse content across different docs. +### Using Hugo shortcodes -For example, to use the note callout: +[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 >}} +{{< note >}}Provide the text of the note here.{{< /note >}} ``` -The callout shortcodes also support multi-line blocks: +The callout shortcodes support multi-line blocks: ```md {{< caution >}} -You should probably never do this specific thing in a production environment. +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 >}} @@ -125,12 +141,14 @@ Supported callouts: - `tip` - `warning` -A few more fun shortcodes: - -- `fa`: inserts a Font Awesome icon -- `img`: include an image and define things like alt text and dimensions -- `include`: include the content of a file in another file; the included file must be present in the content/includes directory -- `link`: makes it possible to link to a file and prepend the path with the Hugo baseUrl -- `openapi`: loads an OpenAPI spec and renders as HTML using ReDoc -- `raw-html`: makes it possible to include a block of raw HTML -- `readfile`: includes the content of another file in the current file; does not require the included file to be in a specific location +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 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. \ No newline at end of file diff --git a/site/go.sum b/site/go.sum index 7db714541b..1cbbb6618c 100644 --- a/site/go.sum +++ b/site/go.sum @@ -1,16 +1,2 @@ -github.com/nginxinc/nginx-hugo-theme v0.28.0 h1:RHHvBmFk2Uptk+efLPSIuBd2elc3IOZPElkJbkkpAHo= -github.com/nginxinc/nginx-hugo-theme v0.28.0/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M= -github.com/nginxinc/nginx-hugo-theme v0.33.0 h1:6mZdgxf5kNhInsrAXXiSlWXRy3fsP51lWKOdrvmkR6U= -github.com/nginxinc/nginx-hugo-theme v0.33.0/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M= -github.com/nginxinc/nginx-hugo-theme v0.34.0-alpha h1:8tKWnkhxP5Nk0V64v8rE9T3crusycohXl3wmOWc4uFk= -github.com/nginxinc/nginx-hugo-theme v0.34.0-alpha/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M= -github.com/nginxinc/nginx-hugo-theme v0.34.0 h1:G7LPVq7w1ls6IS4+OkTwjhFb67rLCzPdfZvW1/sn2Cw= -github.com/nginxinc/nginx-hugo-theme v0.34.0/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M= -github.com/nginxinc/nginx-hugo-theme v0.35.0 h1:7XB2GMy6qeJgKEJy9wOS3SYKYpfvLW3/H+UHRPLM4FU= -github.com/nginxinc/nginx-hugo-theme v0.35.0/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M= -github.com/nginxinc/nginx-hugo-theme v0.40.8 h1:VtoSAtf9k67tI2jzbLRo0oFBAMHZBUPRh/xV4MYullI= -github.com/nginxinc/nginx-hugo-theme v0.40.8/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M= -github.com/nginxinc/nginx-hugo-theme v0.41.9 h1:8TKgjocF95ZSRP0PHkyvk9TyJvwPrdz1k0FB5RfKT3I= -github.com/nginxinc/nginx-hugo-theme v0.41.9/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M= github.com/nginxinc/nginx-hugo-theme v0.41.14 h1:OraNB01CdMJXufPddvIVt6qn6Mj38Z/XCVIWBgVtuY0= github.com/nginxinc/nginx-hugo-theme v0.41.14/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M= diff --git a/site/makefile b/site/makefile deleted file mode 100644 index 849a80b0f4..0000000000 --- a/site/makefile +++ /dev/null @@ -1,94 +0,0 @@ -HUGO?=hugo -HUGO_IMG?=hugomods/hugo:0.115.3 - -THEME_MODULE = github.com/nginxinc/nginx-hugo-theme -## Pulls the current theme version from the Netlify settings -THEME_VERSION = $(NGINX_THEME_VERSION) - -# if there's no local hugo, fallback to docker -ifeq (, $(shell ${HUGO} version 2> /dev/null)) -ifeq (, $(shell docker version 2> /dev/null)) - $(error Docker and Hugo are not installed. Hugo (<0.91) or Docker are required to build the local preview.) -else - HUGO=docker run --rm -it -v ${CURDIR}:/src -p 1313:1313 ${HUGO_IMG} hugo --bind 0.0.0.0 -p 1313 -endif -endif - -MARKDOWNLINT?=markdownlint -MARKDOWNLINT_IMG?=ghcr.io/igorshubovych/markdownlint-cli:latest - -# if there's no local markdownlint, fallback to docker -ifeq (, $(shell ${MARKDOWNLINT} version 2> /dev/null)) -ifeq (, $(shell docker version 2> /dev/null)) -ifneq (, $(shell $(NETLIFY) "true")) - $(error Docker and markdownlint are not installed. markdownlint or Docker are required to lint.) -endif -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 -# if there's no local markdown-link-check, fallback to docker -ifeq (, $(shell ${MARKDOWNLINKCHECK} --version 2> /dev/null)) -ifeq (, $(shell docker version 2> /dev/null)) -ifneq (, $(shell $(NETLIFY) "true")) - $(error Docker and markdown-link-check are not installed. markdown-link-check or Docker are required to check links.) -endif -else - MARKDOWNLINKCHECK=docker run --rm -it -v ${CURDIR}:/docs --workdir /docs ${MARKDOWNLINKCHECK_IMG} -endif -endif - -.PHONY: all clean hugo-mod all-staging all-dev hugo-server-drafts hugo-server netlify deploy-preview - -# Removes the public directory generated by the `hugo` command -clean: - if [[ -d ${PWD}/public ]] ; then rm -rf ${PWD}/public && echo "Removed public directory" ; else echo "Did not find a public directory to remove" ; fi - -hugo-mod: - hugo mod get $(THEME_MODULE)@v$(THEME_VERSION) - -# Builds using the Hugo "production" environment -# For deploys to docs.nginx.com only -all: hugo-mod - hugo --gc -e production - -# Builds using the Hugo "staging" environment -# For deploys to docs-staging.nginx.com only -all-staging: hugo-mod - hugo --gc -e staging - -# Builds using the Hugo "development" environment -# For deploys to docs-dev.nginx.com only -all-dev: hugo-mod - hugo --gc -e development - -# Runs the Hugo server with content marked as draft -# Serves docs at localhost:1313 -docs-drafts: - ${HUGO} server -D --disableFastRender - -docs-local: clean - ${HUGO} - -# Runs the Hugo server -# Serves docs at localhost:1313 -docs: - ${HUGO} server --disableFastRender - -lint-markdown: - ${MARKDOWNLINT} -c .markdownlint.yaml -- content - -link-check: - ${MARKDOWNLINKCHECK} $(shell find content -name '*.md') - -# Can be used to deploy to netlify from your local -# development environment. -# Requires a netlify login. -netlify: clean - netlify deploy --build -d public --alias $(shell git branch --show-current)-branch - -deploy-preview: hugo-mod - hugo --gc -b ${NETLIFY_DEPLOY_URL}/nginx-agent From 867d617ba227349d3d16d12389a8685f41a706b2 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Wed, 4 Sep 2024 09:53:19 +0100 Subject: [PATCH 2/4] Apply suggestions from code review --- site/Makefile | 2 -- 1 file changed, 2 deletions(-) diff --git a/site/Makefile b/site/Makefile index 6b980f1566..2d89f0670d 100644 --- a/site/Makefile +++ b/site/Makefile @@ -17,7 +17,6 @@ MARKDOWNLINT_IMG?=ghcr.io/igorshubovych/markdownlint-cli:latest ifeq (, $(shell ${MARKDOWNLINT} version 2> /dev/null)) ifeq (, $(shell docker version 2> /dev/null)) -ifneq (, $(shell $(NETLIFY) "true")) $(error Docker and markdownlint are not installed. markdownlint or Docker are required to lint.) endif else @@ -30,7 +29,6 @@ MARKDOWNLINKCHECK_IMG?=ghcr.io/tcort/markdown-link-check:stable ifeq (, $(shell ${MARKDOWNLINKCHECK} --version 2> /dev/null)) ifeq (, $(shell docker version 2> /dev/null)) -ifneq (, $(shell $(NETLIFY) "true")) $(error Docker and markdown-link-check are not installed. markdown-link-check or Docker are required to check links.) endif else From 3c714f033bd2b806f7fa0c71288776d91112780e Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Wed, 4 Sep 2024 10:01:28 +0100 Subject: [PATCH 3/4] Update site/Makefile --- site/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/Makefile b/site/Makefile index 2d89f0670d..539a54728a 100644 --- a/site/Makefile +++ b/site/Makefile @@ -32,7 +32,7 @@ ifeq (, $(shell docker version 2> /dev/null)) $(error Docker and markdown-link-check are not installed. markdown-link-check or Docker are required to check links.) endif else - MARKDOWNLINKCHECK=docker run --rm -it -v ${CURDIR}:/docs --workdir /docs ${MARKDOWNLINKCHECK_IMG} + MARKDOWNLINKCHECK=docker run --rm -it -v ${CURDIR}:/site --workdir /site ${MARKDOWNLINKCHECK_IMG} endif endif From 2a0ccd232df668af6a6286c1d01dba4cf54843a7 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Wed, 4 Sep 2024 12:32:59 +0100 Subject: [PATCH 4/4] Update .PHONY --- site/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/Makefile b/site/Makefile index 539a54728a..fbc4f9e645 100644 --- a/site/Makefile +++ b/site/Makefile @@ -36,7 +36,7 @@ else endif endif -.PHONY: docs docs-draft docs-local clean hugo-get hugo-tidy lint-markdown link-check +.PHONY: docs watch drafts clean hugo-get hugo-tidy hugo-update lint-markdown link-check docs: ${HUGO}