From 3ddc80e3fb152728d8d441e335f0ba57c5e63fd0 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Wed, 4 Sep 2024 10:05:37 +0100 Subject: [PATCH 1/3] Update documentation Makefile and README This commit updates the documentation Makefile and README, removing references to Netlify and clarifying the usage of the Makefile. This is part of an effort to ensure they remain consistent across all NGINX repositories. --- site/Makefile | 53 ++++++++++++++------------------------------------ site/README.md | 31 ++++++++++++++--------------- 2 files changed, 30 insertions(+), 54 deletions(-) diff --git a/site/Makefile b/site/Makefile index e0ee3dd0aa..71c9476da7 100644 --- a/site/Makefile +++ b/site/Makefile @@ -1,28 +1,22 @@ HUGO?=hugo -# the officially recommended unofficial docker image 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) -NETLIFY_DEPLOY_URL = ${DEPLOY_PRIME_URL} +THEME_VERSION = 0.41.14 -# 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 + 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 @@ -32,10 +26,9 @@ 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 @@ -43,46 +36,30 @@ else endif endif -.PHONY: all all-staging all-dev all-local clean hugo-mod build-production build-staging build-dev docs-drafts docs deploy-preview - -all: hugo-mod build-production - -all-staging: hugo-mod build-staging - -all-dev: hugo-mod build-dev - -all-local: clean hugo-mod build-production +.PHONY: docs docs-draft docs-local clean hugo-get hugo-tidy lint-markdown link-check docs: ${HUGO} -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 - watch: ${HUGO} --bind 0.0.0.0 -p 1313 server --disableFastRender -watch-drafts: +drafts: ${HUGO} --bind 0.0.0.0 -p 1313 server -D --disableFastRender -link-check: - ${MARKDOWNLINKCHECK} $(shell find content -name '*.md') - -lint-markdown: - ${MARKDOWNLINT} -c .markdownlint.json -- content +clean: + [ -d "public" ] && rm -rf "public" -# Commands used by Netlify CI -hugo-mod: +hugo-get: hugo mod get $(THEME_MODULE)@v$(THEME_VERSION) -build-production: - hugo --gc -e production +hugo-tidy: + hugo mod tidy -build-staging: - hugo --gc -e staging +hugo-update: hugo-get hugo-tidy -build-dev: - hugo --gc -e development +lint-markdown: + ${MARKDOWNLINT} -c .markdownlint.yaml -- content -deploy-preview: hugo-mod - hugo --gc -b ${NETLIFY_DEPLOY_URL}/nginx-gateway-fabric/ +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 98c5d36e80..5128219d77 100644 --- a/site/README.md +++ b/site/README.md @@ -38,28 +38,27 @@ The documentation is published from the latest public release branch. If your ch ## Developing documentation locally -To build the documentation locally, run the `make` command inside this `/site/` directory: +To build the documentation locally, use the `make` command in the documentation folder with these targets: ```text -make docs - Builds the documentation set with the output as the '/public' directory -make clean - Removes the local '/public/' directory -make watch - Starts a local Hugo server for live previews -make watch-drafts - Starts a local Hugo server for live previews, including documentation marked with 'draft: true' -make link-check - Check for any broken links in the documentation -make lint-markdown - Runs markdownlint to identify possible markdown formatting issues +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 ``` -The `watch` options automatically reload the Hugo server, allowing you to view updates as you work. - -> **Note**: The documentation uses build environments to control the baseURL used for things like internal references and static resources. The configuration for each environment can be found in the `config` directory. When running Hugo you can specify the environment and baseURL, but it's unnecessary. - ## Adding new documentation -### Using Hugo to generate a new documentation file +### Generate a new documentation file using Hugo -To create a new documentation file with the pre-configured Hugo front-matter for the task template, run the following command inside this `/site` 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 /.md` +`hugo new /.` For example: @@ -67,7 +66,7 @@ For example: hugo new getting-started/install.md ``` -The default template (task) should be used for most pages. For 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 @@ -125,7 +124,7 @@ Use the `img` [shortcode](#using-hugo-shortcodes) to add images into your docume ### Using Hugo shortcodes -[Hugo shortcodes](/docs/themes/f5-hugo/layouts/shortcodes/) are used to format callouts, add images, and reuse content across different pages. +[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: From c6ff590fcf691fa8577f956b06bad8ba13112f83 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 4 Sep 2024 09:19:56 +0000 Subject: [PATCH 2/3] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- site/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/Makefile b/site/Makefile index 71c9476da7..d46833e92a 100644 --- a/site/Makefile +++ b/site/Makefile @@ -62,4 +62,4 @@ lint-markdown: ${MARKDOWNLINT} -c .markdownlint.yaml -- content link-check: - ${MARKDOWNLINKCHECK} $(shell find content -name '*.md') \ No newline at end of file + ${MARKDOWNLINKCHECK} $(shell find content -name '*.md') From 3626435eed23064bdf674d95e42b3d82794130da Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Wed, 4 Sep 2024 12:34:40 +0100 Subject: [PATCH 3/3] Update site/Makefile --- site/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/Makefile b/site/Makefile index d46833e92a..8b0ab44676 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}