Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update documentation Makefile and README #2507

Merged
merged 6 commits into from
Sep 4, 2024
+30 −54
Merged

Update documentation Makefile and README #2507

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
3ddc80e
Update documentation Makefile and README
ADubhlaoich Sep 4, 2024
efc56c3
Merge branch 'main' into update-makefile-readme
ADubhlaoich Sep 4, 2024
790e6d9
Merge branch 'main' into update-makefile-readme
ADubhlaoich Sep 4, 2024
c6ff590
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Sep 4, 2024
3626435
Update site/Makefile
ADubhlaoich Sep 4, 2024
3dcd6ef
Merge branch 'main' into update-makefile-readme
ADubhlaoich Sep 4, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 15 additions & 38 deletions site/Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
ADubhlaoich marked this conversation as resolved.
Show resolved Hide resolved

# 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
Expand All @@ -32,57 +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 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')
31 changes: 15 additions & 16 deletions site/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,36 +38,35 @@ 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 <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
Expand Down Expand Up @@ -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:

Expand Down
Loading