diff --git a/.github/workflows/docs-build-push.yml b/.github/workflows/docs-build-push.yml index 3e6f1db7fd..5e0741603e 100644 --- a/.github/workflows/docs-build-push.yml +++ b/.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 diff --git a/site/Makefile b/site/Makefile index e0ee3dd0aa..8b0ab44676 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 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') 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: