Update guidance and tooling for documentation

site/Makefile

@@ -12,7 +12,7 @@ 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 --bind 0.0.0.0 -p 1313
+    HUGO=docker run --rm -it -v ${CURDIR}:/src -p 1313:1313 ${HUGO_IMG} hugo 
 endif
 endif
 
@@ -43,7 +43,6 @@ 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
@@ -55,27 +54,25 @@ all-dev: hugo-mod build-dev
 all-local: clean hugo-mod build-production
 
 # Removes the public directory generated by the `hugo` command
+build:
+	${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
 
-docs-drafts:
-	${HUGO} server -D --disableFastRender
-
-docs-local: clean
-	${HUGO}
-
-docs:
-	${HUGO} server --disableFastRender
-
-lint-markdown:
-	${MARKDOWNLINT} -c .markdownlint.yaml  -- content
+watch-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.yaml  -- content
 
-## commands for use in Netlify CI
+# Commands used by Netlify CI
 hugo-mod:
 	hugo mod get $(THEME_MODULE)@v$(THEME_VERSION)
 

site/README.md

@@ -0,0 +1,137 @@
+# NGINX Gateway Fabric Documentation
+
+This directory contains all of the user documentation for NGINX Gateway Fabric, as well as the requirements for building and publishing the documentation.
+
+Documentation is written in Markdown, built using [Hugo](https://gohugo.io) with [nginx-hugo-theme](https://github.com/nginxinc/nginx-hugo-theme), then deployed with [Netlify](https://www.netlify.com/).
+
+## Setup
+
+Hugo is the only requirement for building documentation.
+
+To install Hugo locally, follow the [official Hugo 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.
+
+If you have [Docker](https://www.docker.com/get-started/) installed, there is a fallback in the [Makefile](Makefile) which means you do need to install Hugo locally.
+
+## Developing documentation locally
+
+To build the documentation locally, run the `make` command inside this `/site/` directory:
+
+```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 link-markdown   - Runs markdownlint to identify possible markdown formatting issues
+```
+
+## Adding new documentation
+
+### Using Hugo to generate a new documentation file
+
+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:
+
+`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:
+
+```shell
+hugo new tutorials/deploy.md --kind tutorial
+```
+
+The available content templates (`kind`) are:
+
+- concept: Help a user learn about a specific feature or feature set.
+- tutorial: Walk a user through an example use case scenario.
+- reference: Describes an API, command line tool, configuration options, etc.
+- troubleshooting: Guide a user towards solving a specific problem.
+- openapi: A template with the requirements to render an openapi.yaml specification.
+
+## Documentation formatting
+
+### Basic markdown formatting
+
+There are multiple ways to format text: for consistency and clarity, these are our conventions:
+
+- Bold: Two asterisks on each side - `**Bolded text**`.
+- Italic: One underscore on each side - `_Italicized text_`.
+- Unordered lists: One dash - `- Unordered list item`.
+- Ordered lists: The 1 character followed by a stop - `1. Ordered list item`.
+
+> **Note**: The ordered notation automatically enumerates lists when built by Hugo.
+
+Close every section with a horizontal line by using three dashes: `---`.
+
+### How to format internal links
+
+Internal links should use Hugo [ref and relref shortcodes](https://gohugo.io/content-management/cross-references/).
+
+- Although file extensions are optional for Hugo, we include them as best practice for page anchors.
+- Relative paths are preferred, but just the filename is permissible.
+- Paths without a leading forward slash (`/`) are first resolved relative to the current page, then the remainder of the website.
+
+Here are two examples:
+
+```md
+To install <software>, refer to the [installation instructions]({{< ref "install.md" >}}).
+To install <integation>, refer to the [integration instructions]({{< relref "/integration/thing.md#section" >}}).
+```
+
+### How to add images
+
+Use the `img` [shortcode](#using-hugo-shortcodes) to add images into your documentation.
+
+1. Add the image to the `/static/img` directory.
+1. Add the `img` shortcode:
+    `{{< img src="<img-file.png>" >}}`
+   - **Do not include a forward slash at the beginning of the file path.**
+   - This will break the image when it's rendered: read about the  [Hugo relURL Function](https://gohugo.io/functions/relurl/#input-begins-with-a-slash) to learn more.
+
+
+> **Note**: The `img` shortcode accepts all of the same parameters as the Hugo [figure shortcode](https://gohugo.io/content-management/shortcodes/#figure).
+
+### Using Hugo shortcodes
+
+[Hugo shortcodes](/docs/themes/f5-hugo/layouts/shortcodes/) are used to format callouts, add images, and reuse content across different pages.
+
+For example, to use the `note` callout:
+
+```md
+{{< note >}}Provide the text of the note here.{{< /note >}}
+```
+
+The callout shortcodes 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`
+
+Here are some other shortcodes:
+
+- `fa`: Inserts a Font Awesome icon
+- `include`: Include the content of a file in another file; the included file must be present in the '/content/includes/' directory
+- `link`: Link to a file, prepending its path with the Hugo baseUrl
+- `openapi`: Loads an OpenAPI specifcation and render it as HTML using ReDoc
+- `raw-html`: Include a block of raw HTML
+- `readfile`: Include the content of another file in the current file, which can be in an arbitrary location.