Upgrade nginx-hugo-theme version to support newer Hugo releases (#4149)…

… (#4178)

- Updates Makefile and netlify configuration file to
make sure the hugo mod command is run for deploy
preview and branch deploy builds

- Adds docs/README with instructions for using hugo

- Updates nginx-hugo-theme module

docs/Makefile

@@ -47,3 +47,6 @@ docs:
 # 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-ingress-controller

docs/README.md

@@ -1,19 +1,120 @@
-# How To Contribute
-## Introduction
-The NGINX Ingress Controller makes use of the [Hugo](https://gohugo.io/) static site generator.
+# NGINX Ingress Controller Docs
 
-Documentation is stored within the `docs/` subfolder of the main repository, and is where `hugo` commands should be run.
+This directory contains all of the user documentation for NGINX Ingress Controller, as well as the requirements for linting, building, and publishing the documentation.
 
-Hugo will watch and reload any changes made, so you can review your work in real time.
+Docs are written in Markdown. We build the docs using [Hugo](https://gohugo.io) and host them on [Netlify](https://www.netlify.com/).
 
-## Set-up
-**Requirements**
-* [git](https://git-scm.com/downloads)
-* [hugo](https://gohugo.io/installation/)
+## Setup
 
-**Quick Start**
+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.
+
+## Local Docs Development
+
+To build the docs locally, run the desired `make` command from the docs directory:
+
+```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`
+```
+
+## Add new docs
+
+### Generate a new doc 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**:
+
+`hugo new <SECTIONNAME>/<FILENAME>.<FORMAT>`
+
+For example:
+
+```shell
+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:
+
+```shell
+hugo new tutorials/deploy.md --kind tutorial
+```
+
+The available content types (`kind`) are:
+
+- concept: Helps a customer learn about a specific feature or feature set.
+- tutorial: Walks a customer through an example use case scenario; results in a functional PoC environment.
+- reference: Describes an API, command line tool, config options, etc.; should be generated automatically from source code.
+- troubleshooting: Helps a customer solve a specific problem.
+- openapi: Contains front-matter and shortcode for rendering an openapi.yaml spec
+
+## How to format docs
+
+### How to format internal links
+
+Format links as [Hugo refs](https://gohugo.io/content-management/cross-references/).
+
+- 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.
+
+For example:
+
+```md
+To install <product>, refer to the [installation instructions]({{< ref "install" >}}).
 ```
-git clone [email protected]:nginxinc/kubernetes-ingress.git
-cd docs/
-hugo server
+
+### How to include images
+
+You can use the `img` [shortcode](#how-to-use-hugo-shortcodes) to add images into your documentation.
+
+1. Add the image to the static/img directory, or to the same directory as the doc you want to use it in.
+
+   - **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.
+
+1. Add the img shortcode:
+
+    {{< img src="<img-file.png>" >}}
+
+> Note: The shortcode accepts all of the same parameters as the [Hugo figure shortcode](https://gohugo.io/content-management/shortcodes/#figure).
+
+### How to use Hugo shortcodes
+
+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.
+
+For example, to use the note callout:
+
+```md
+{{< note >}}Provide the text of the note here. {{< /note >}}
+```
+
+The callout shortcodes also support multi-line blocks:
+
+```md
+{{< caution >}}
+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 >}}
 ```
+
+Supported callouts:
+
+- `caution`
+- `important`
+- `note`
+- `see-also`
+- `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.

docs/content/intro/how-nginx-ingress-controller-works.md

@@ -210,7 +210,7 @@ The Controller [sync](https://github.com/nginxinc/kubernetes-ingress/blob/v1.11.
 
 Rather than show how all the various sync methods work, we focus on the most important one -- the *syncIngress* method -- and look at how it processes a new Ingress resource, illustrated in the diagram below.
 
-{{< img src="/img/controller-sync.png" title="Controller sync" >}}
+{{< img src="img/controller-sync.png" title="Controller sync" >}}
 
 1. The *Workqueue* calls the *sync* method and passes a workqueue element to it that includes the changed resource *kind* and *key* (the key is the resource namespace/name like “default/cafe-ingress”).
 2. Using the *kind*, the *sync* method calls the appropriate sync method and passes the resource key. For Ingresses, that method is *syncIngress*.

docs/go.mod

@@ -2,4 +2,4 @@ module github.com/nginxinc/kubernetes-ingress/docs
 
 go 1.19
 
-require github.com/nginxinc/nginx-hugo-theme v0.33.0
+require github.com/nginxinc/nginx-hugo-theme v0.34.0

docs/go.sum

@@ -1,4 +1,7 @@
 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.32.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 h1:G7LPVq7w1ls6IS4+OkTwjhFb67rLCzPdfZvW1/sn2Cw=
+github.com/nginxinc/nginx-hugo-theme v0.34.0/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M=

netlify.toml

@@ -13,10 +13,10 @@
   command = "make all"
 
 [context.deploy-preview]
-  command = "hugo --gc -b $DEPLOY_PRIME_URL/nginx-ingress-controller"
+  command = "make deploy-preview"
 
 [context.branch-deploy]
-  command = "hugo --gc -b $DEPLOY_PRIME_URL/nginx-ingress-controller"
+  command = "make deploy-preview"
 
 [[headers]]
   for = "/*"