Merge branch 'main' into chore/release-process-docs

.github/workflows/docs-build-push.yml

@@ -41,7 +41,7 @@ jobs:
   call-docs-build-push:
     needs: [vars]
     if: ${{ github.event.repository.fork == false && needs.vars.outputs.azure_creds == 'true' }}
-    uses: nginxinc/docs-actions/.github/workflows/docs-build-push.yml@a733e84a262f8d5d885bfc8eac80bc85928da322 # v1.0.3
+    uses: nginxinc/docs-actions/.github/workflows/docs-build-push.yml@d20def4d420028a71f99863011c6de7325c4013e # v1.0.4
     permissions:
       pull-requests: write # needed to write preview url comment to PR
       contents: read

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,57 +26,40 @@ 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}:/site --workdir /site ${MARKDOWNLINKCHECK_IMG}
 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 watch drafts clean hugo-get hugo-tidy hugo-update 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')

site/README.md

@@ -38,36 +38,35 @@ 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 <SECTIONNAME>/<FILENAME>.md`
+`hugo new <SECTIONNAME>/<FILENAME>.<FORMAT>`
 
 For example:
 
 ```shell
 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: