Update documentation Makefile and README (#6339)

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.

Author: ADubhlaoich

docs/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 = 0.41.14
-NETLIFY_DEPLOY_URL = ${DEPLOY_PRIME_URL}
 
-# 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,60 +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 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)
 
 hugo-tidy:
 	hugo mod tidy
 
-build-production:
-	hugo --gc -e production
+hugo-update: hugo-get hugo-tidy
 
-build-staging:
-	hugo --gc -e staging
-
-build-dev:
-	hugo --gc -e development
+lint-markdown:
+	${MARKDOWNLINT} -c .markdownlint.yaml  -- content
 
-deploy-preview: hugo-mod
-	hugo --gc -b ${NETLIFY_DEPLOY_URL}/nginx-ingress-controller/
+link-check:
+	${MARKDOWNLINKCHECK} $(shell find content -name '*.md')

docs/README.md

@@ -30,38 +30,37 @@ To work on documentation, create a feature branch in a forked repository then ta
 
 The documentation is published from the latest public release branch. If your changes require immediate publication, create a pull request to cherry-pick changes from `main` to the public release branch.
 
-## Developing documentation locally
+## Develop 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
@@ -119,7 +118,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: