From bbaa2ba98b4ba4326bd82ab84e540540e34b86e4 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Fri, 29 Dec 2023 17:06:17 +0000 Subject: [PATCH 1/8] Add documentation README to /site subfolder This commit adds a README file to the /site subfolder instructing a reader on how to build and contribute to the documentation. It introduces the tooling, explains the Makefile, then details the conventions around Hugo and Markdown usage. --- site/README.md | 133 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 133 insertions(+) create mode 100644 site/README.md diff --git a/site/README.md b/site/README.md new file mode 100644 index 000000000..3032055e2 --- /dev/null +++ b/site/README.md @@ -0,0 +1,133 @@ +# 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) and 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 docs locally, run the `make` command inside this `/docs` directory: + +```text +make clean - Removes the local `public` directory, which is the default output path used by Hugo +make docs - Start a local Hugo server for live previews while editing +make docs-drafts - Start a local Hugo server for live previews, including documentation marked with `draft: true` +make hugo-mod - Cleans the Hugo module cache and fetches the latest version of the theme +make hugo-mod-tidy - Removes unused entries in go.mod and go.sum, then verifies the dependencies +``` + +## 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 `/docs` directory: + +`hugo new /.` + +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 , refer to the [installation instructions]({{< ref "install.md" >}}). +To install , refer to the [integration instructions]({{< relref "/integration/thing.md#section" >}}). +``` + +### How to add images + +Use the `img` [shortcode](#how-to-use-hugo-shortcodes) to add images into your documentation. + +1. Add the image to the `/static/img` directory. +1. Add the `img` shortcode: + `{{< img src="" >}}` + - **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 docs. + +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 +- `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. \ No newline at end of file From e7160e3fc804ee5f72d9ab7e40004e241aa30d13 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Tue, 2 Jan 2024 09:13:59 +0000 Subject: [PATCH 2/8] feat: Fix linting issues --- site/README.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/site/README.md b/site/README.md index 3032055e2..52a7cf859 100644 --- a/site/README.md +++ b/site/README.md @@ -15,6 +15,7 @@ To install Hugo locally, follow the [official Hugo instructions](https://gohugo. 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 docs locally, run the `make` command inside this `/docs` directory: ```text @@ -26,6 +27,7 @@ make hugo-mod-tidy - Removes unused entries in go.mod and go.sum, then verifi ``` ## 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 `/docs` directory: @@ -53,7 +55,9 @@ The available content templates (`kind`) are: - 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**`. @@ -70,7 +74,7 @@ Close every section with a horizontal line by using three dashes: `---`. 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. +- 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: @@ -82,7 +86,7 @@ To install , refer to the [integration instructions]({{< relref "/in ### How to add images -Use the `img` [shortcode](#how-to-use-hugo-shortcodes) to add images into your documentation. +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: @@ -130,4 +134,4 @@ Here are some other shortcodes: - `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. \ No newline at end of file +- `readfile`: includes the content of another file in the current file; does not require the included file to be in a specific location. From 966498370f71bfb0af7548db79340462cd3ace45 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Fri, 5 Jan 2024 17:11:53 +0000 Subject: [PATCH 3/8] Update documentation makefile and README This commit incorporates some feedback to the README file while also updating the Makefile to follow suit. There were some options listed that didn't actually exist and others that weren't listed. --- site/Makefile | 25 +++++++++++-------------- site/README.md | 32 ++++++++++++++++---------------- 2 files changed, 27 insertions(+), 30 deletions(-) diff --git a/site/Makefile b/site/Makefile index 1e0dcedb4..5cd34938c 100644 --- a/site/Makefile +++ b/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) diff --git a/site/README.md b/site/README.md index 52a7cf859..8d02872d4 100644 --- a/site/README.md +++ b/site/README.md @@ -2,7 +2,7 @@ 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) and deployed with [Netlify](https://www.netlify.com/). +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 @@ -16,21 +16,22 @@ If you have [Docker](https://www.docker.com/get-started/) installed, there is a ## Developing documentation locally -To build the docs locally, run the `make` command inside this `/docs` directory: +To build the documentation locally, run the `make` command inside this `/site/` directory: ```text -make clean - Removes the local `public` directory, which is the default output path used by Hugo -make docs - Start a local Hugo server for live previews while editing -make docs-drafts - Start a local Hugo server for live previews, including documentation marked with `draft: true` -make hugo-mod - Cleans the Hugo module cache and fetches the latest version of the theme -make hugo-mod-tidy - Removes unused entries in go.mod and go.sum, then verifies the dependencies +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 `/docs` directory: +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 /.` @@ -99,7 +100,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 docs. +[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: @@ -128,10 +129,9 @@ Supported callouts: Here are some other 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. +- `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. From 7a67e89cd6a72307fe6ca40338456aca3babd403 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Mon, 8 Jan 2024 12:28:39 +0000 Subject: [PATCH 4/8] Update site/README.md Co-authored-by: Saylor Berman --- site/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/README.md b/site/README.md index 8d02872d4..ba5c13691 100644 --- a/site/README.md +++ b/site/README.md @@ -24,7 +24,7 @@ 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 +make lint-markdown - Runs markdownlint to identify possible markdown formatting issues ``` ## Adding new documentation From fa6ca33e1587f170ac50f093fccb76c32ee66501 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Mon, 8 Jan 2024 13:24:43 +0000 Subject: [PATCH 5/8] Update docs README, remove redundant doc, add references in CONTRIBUTING --- CONTRIBUTING.md | 2 + docs/developer/documentation.md | 165 -------------------------------- site/README.md | 42 ++++++-- 3 files changed, 37 insertions(+), 172 deletions(-) delete mode 100644 docs/developer/documentation.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c4937f6bd..d3ed1dc68 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -43,6 +43,7 @@ Follow our [Installation Instructions](https://docs.nginx.com/nginx-gateway-fabr - We use [Go Modules](https://github.com/golang/go/wiki/Modules) for managing dependencies. - We use [Ginkgo](https://onsi.github.io/ginkgo/) and [Gomega](https://onsi.github.io/gomega/) for our BDD style unit tests. +- The documentation website is found under `site/` ## Contributing @@ -93,6 +94,7 @@ Before beginning development, familiarize yourself with the following documents: conventions to follow when writing Go code for the project. - [Architecture](https://docs.nginx.com/nginx-gateway-fabric/overview/gateway-architecture/): A high-level overview of the project's architecture. - [Design Principles](/docs/developer/design-principles.md): An overview of the project's design principles. +- [NGINX Gateway Fabric Documentation](/site/README.md): An explanation of the documentation tooling and conventions. ## Contributor License Agreement diff --git a/docs/developer/documentation.md b/docs/developer/documentation.md deleted file mode 100644 index f927fa59b..000000000 --- a/docs/developer/documentation.md +++ /dev/null @@ -1,165 +0,0 @@ -# NGINX Gateway Fabric Docs - -The `/site` directory contains the user documentation for NGINX Gateway Fabric and the requirements for linting, building, and publishing the docs. Run all the `hugo` commands below from this directory. - -We use [Hugo](https://gohugo.io/) to build the docs for NGINX, with the [nginx-hugo-theme](https://github.com/nginxinc/nginx-hugo-theme). - -Docs should be written in Markdown. - -In the `/site` directory, you will find the following files: - -- a [Netlify](https://netlify.com) configuration file; -- configuration files for [markdownlint](https://github.com/DavidAnson/markdownlint/) and [markdown-link-check](https://github.com/tcort/markdown-link-check) -- a `./config` directory that contains the [Hugo](https://gohugo.io) configuration. - -## Git Guidelines - -See the [Pull Request Guide](pull-request.md) for specfic instructions on how to submit a pull request. - -### Branching and Workflow - -This repo uses a [forking workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow). See our [Branching and Workflow](branching-and-workflow.md) documentation for more information. - -### Publishing Documentation Updates - -**`main`** is the default branch in this repo. All the latest content updates are merged into this branch. - -The documentation is published from the latest public release branch, (for example, `release-4.0`). Work on your docs in a feature branch in your fork of the repo. Open pull requests into the `main` branch when you are ready to merge your work. - -If you are working on content for immediate publication in the docs site, cherrypick your changes to the current public release branch. - -If you are working on content for a future release, make sure that you **do not** cherrypick them to the current public release branch, as this will publish them automatically. See the [Release Process documentation](release-process.md) for more information. - - -## Setup - -### Golang - -Follow the instructions here to install Go: https://golang.org/doc/install - -> To support the use of Hugo mods, you need to install Go v1.15 or newer. - -### Hugo - -Follow the instructions here to install Hugo: [Hugo Installation](https://gohugo.io/installation/) - -> **NOTE:** We are currently running [Hugo v0.115.3](https://github.com/gohugoio/hugo/releases/tag/v0.115.3) in production. - -### Markdownlint - -We use markdownlint to check that Markdown files are correctly formatted. You can use `npm` to install markdownlint-cli: - -```shell -npm install -g markdownlint-cli -``` - -## How to write docs with Hugo - -### Add a new doc - -- To create a new doc that contains all of the pre-configured Hugo front-matter and the docs task template: - - `hugo new /.` - - e.g., - - hugo new install.md - - > The default template -- task -- should be used in most docs. -- To create other types of docs, you can add the `--kind` flag: - `hugo new tutorials/deploy.md --kind tutorial` - - -The available kinds are: - -- Task: Enable the customer to achieve a specific goal, based on use case scenarios. -- Concept: Help a customer learn about a specific feature or feature set. -- 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. -- Tutorial: Walk a customer through an example use case scenario; results in a functional PoC environment. - -### Format internal links - -Format links as [Hugo relrefs](https://gohugo.io/content-management/cross-references/). - -> Note: Using file extensions when linking to internal docs with `relref` is optional. - -- You can use relative paths or just the filename. We recommend using 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 NGINX Gateway Fabric, refer to the [installation instructions]({{< relref "/installation/install.md#section-1" >}}). -``` - -### Add images - -You can use the `img` [shortcode](#use-hugo-shortcodes to insert images into your documentation. - -1. Add the image to the static/img directory. - 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/" >}} - -> Note: The shortcode accepts all of the same parameters as the [Hugo figure shortcode](https://gohugo.io/content-management/shortcodes/#figure). - -### Use Hugo shortcodes - -You can use Hugo [shortcodes](https://gohugo.io/content-management/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 useful shortcodes: - -- collapse: makes a section collapsible -- table: adds scrollbars to wide tables when viewed in small browser windows or mobile browsers -- fa: inserts a Font Awesome icon -- include: include the content of a file in another file (requires the included file to be in the /includes directory) -- link: makes it possible to link to a static 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; useful for adding code examples - -## How to build docs locally - -To view the docs in a browser, run the Hugo server. This will reload the docs automatically so you can view updates as you work. - -> Note: The docs use build environments to control the baseURL that will be used for things like internal references and resource (CSS and JS) loading. -> You can view the config for each environment in the [config](./config) directory of this repo. -When running the Hugo server, you can specify the environment and baseURL if desired, but it's not necessary. - -For example: - -```shell -hugo server -``` - -```shell -hugo server -e development -b "http://127.0.0.1/nginx-gateway-fabric/" -``` diff --git a/site/README.md b/site/README.md index ba5c13691..9a4c77927 100644 --- a/site/README.md +++ b/site/README.md @@ -6,13 +6,35 @@ Documentation is written in Markdown, built using [Hugo](https://gohugo.io) with ## Setup -Hugo is the only requirement for building documentation. +Hugo is the only requirement for building documentation, but the repository's integration tooling uses markdownlint-cli. -To install Hugo locally, follow the [official Hugo instructions](https://gohugo.io/getting-started/installing/). +> **Note**: We currently use [Hugo v0.115.3](https://github.com/gohugoio/hugo/releases/tag/v0.115.3) in production. -> **Note**: We are currently running [Hugo v0.115.3](https://github.com/gohugoio/hugo/releases/tag/v0.115.3) in production. +Although not a strict requirement, markdown-link-check is also used in documentation development. -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. +If you have [Docker](https://www.docker.com/get-started/) installed, there are fallbacks for all in the [Makefile](Makefile), meaning you do need to install them. + +- [Installing Hugo](https://gohugo.io/getting-started/installing/) +- [Installing markdownlint-cli](https://github.com/igorshubovych/markdownlint-cli?tab=readme-ov-file#installation) +- [Installing markdown-link-check](https://github.com/tcort/markdown-link-check?tab=readme-ov-file#installation). + +The configuration files are as follows: + +- *Hugo*: `config/default/config.toml` +- *markdownlint-cli*: `mdlint_conf.json` +- *markdown-link-check* `md-linkcheck-config.json` + +## Repository guidelines + +Documentation follows the conventions of the regular codebase: use the following guides. + +- [Pull Request Guidelines](../docs/developer/pull-request.md) +- [Branching and Workflow](../docs/developerr/branching-and-workflow.md) +- [Release Process](../docs/developer/developer/release-process.md) + +To work on documentation, create a feature branch in a forked repository then target `main` with your pull requests, which is the default repository branch. + +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 @@ -27,13 +49,17 @@ make link-check - Check for any broken links in the documentation make lint-markdown - Runs markdownlint to identify possible markdown formatting issues ``` +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 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 /.` +`hugo new /.md` For example: @@ -95,7 +121,6 @@ Use the `img` [shortcode](#using-hugo-shortcodes) to add images into your docume - **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 @@ -130,8 +155,11 @@ Supported callouts: 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 +- `collapse`: Make a section collapsible +- `tab`: Create mutually exclusive tabbed window panes, useful for parallel instructions +- `table`: Add scrollbars to wide tables for browsers with smaller viewports - `link`: Link to a file, prepending its path with the Hugo baseUrl - `openapi`: Loads an OpenAPI specifcation and render it as HTML using ReDoc +- `include`: Include the content of a file in another file; the included file must be present in the '/content/includes/' directory - `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. From a4e45700110b13726772f3fd116be785aaf1a7e6 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Mon, 8 Jan 2024 13:40:55 +0000 Subject: [PATCH 6/8] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- site/Makefile | 2 +- site/README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/site/Makefile b/site/Makefile index 5cd34938c..a8f5e309c 100644 --- a/site/Makefile +++ b/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 + HUGO=docker run --rm -it -v ${CURDIR}:/src -p 1313:1313 ${HUGO_IMG} hugo endif endif diff --git a/site/README.md b/site/README.md index 9a4c77927..97a4e7c8f 100644 --- a/site/README.md +++ b/site/README.md @@ -41,7 +41,7 @@ The documentation is published from the latest public release branch. If your ch 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 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' From d905398ba40acacf70124975b97cbfe6d0c786cd Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Tue, 9 Jan 2024 11:05:40 +0000 Subject: [PATCH 7/8] Update CONTRIBUTING.md Co-authored-by: Saylor Berman --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d3ed1dc68..506706ddc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -43,7 +43,7 @@ Follow our [Installation Instructions](https://docs.nginx.com/nginx-gateway-fabr - We use [Go Modules](https://github.com/golang/go/wiki/Modules) for managing dependencies. - We use [Ginkgo](https://onsi.github.io/ginkgo/) and [Gomega](https://onsi.github.io/gomega/) for our BDD style unit tests. -- The documentation website is found under `site/` +- The documentation website is found under `site/`. ## Contributing From 40125815dc30b313618481a5dacdc6549d48206b Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Tue, 9 Jan 2024 12:45:57 +0000 Subject: [PATCH 8/8] Change docs Maketile target named "build" to "docs" --- site/Makefile | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/site/Makefile b/site/Makefile index a8f5e309c..2ace06908 100644 --- a/site/Makefile +++ b/site/Makefile @@ -53,8 +53,7 @@ all-dev: hugo-mod build-dev all-local: clean hugo-mod build-production -# Removes the public directory generated by the `hugo` command -build: +docs: ${HUGO} clean: