From 041d759c238e2c74499cb62947a9ff1f71dab82b Mon Sep 17 00:00:00 2001 From: Travis Martin Date: Thu, 3 Sep 2026 13:24:42 -0700 Subject: [PATCH 1/2] chore: Update F5 style guide submodule --- .style-guide | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.style-guide b/.style-guide index 7f524bf55..98aa29d39 160000 --- a/.style-guide +++ b/.style-guide @@ -1 +1 @@ -Subproject commit 7f524bf55380c6b67fbbedc7842ee4d2ff39da06 +Subproject commit 98aa29d39009a02582b9c6d6214acac1a7ee624c From 660e70a466da01910ddb5e3ba3fe1332ab5f471b Mon Sep 17 00:00:00 2001 From: Travis Martin Date: Thu, 3 Sep 2026 13:39:56 -0700 Subject: [PATCH 2/2] Added agent instruction files. --- .github/copilot-instructions.md | 249 +------------------------------- AGENTS.md | 243 +++++++++++++++++++++++++++++++ CLAUDE.md | 240 +----------------------------- opencode.json | 4 + 4 files changed, 251 insertions(+), 485 deletions(-) create mode 100644 AGENTS.md create mode 100644 opencode.json diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 32bab5ac1..884d1bfec 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,248 +1,3 @@ -# F5 Tech Writer Agent +# NGINX Documentation -## Agent instructions - -Before responding to any request in this repo, read -`.style-guide/agent-instructions/f5-tech-writer-agent.md` in full. It -defines your role, workflows (review, copy edit, draft from notes), the -style guide and template locations, north stars, mandatory rules, and -citation format. Treat it as your primary instructions for this repo. - -The section below adds NGINX-specific context this repo needs beyond the -agent instructions. Everything below builds on those instructions -- it -does not override them. - -## Hugo includes - -Some docs use Hugo shortcodes to include content from other files, for example: - - {{< include file="path/to/file.md" >}} - -When you encounter an include shortcode in a file you are editing, read the -included file and review it for style issues as part of the same task. Apply -the same style rules to included files. List changes to included files -separately in your output, citing the filename. - ---- - -## Repo overview - -This is a Hugo-based documentation site for F5 NGINX products (NGINX Plus, -NGINX Ingress Controller, NGINX Gateway Fabric, WAF, Instance Manager, etc.). -Content is written in Markdown with Hugo shortcodes, transformed to HTML via -Hugo v0.152.2, using the custom theme `github.com/nginxinc/nginx-hugo-theme/v2`. - -## Build and dev commands - -```bash -# Update Hugo theme before starting work -make hugo-update - -# Local development server -make watch # http://localhost:1313 - -# Include draft content -make drafts - -# Build for production -make docs # outputs to public/ - -# Linting -make lint-markdown # markdownlint-cli2 -make link-check # markdown-link-check -``` - -## Content structure - -- `content/` -- Product documentation organized by product code (`nic/`, `ngf/`, `waf/`, `nim/`, `agent/`, etc.) -- `content/includes/` -- Reusable content fragments (for example, `content/includes/waf/terminology.md`) -- `archetypes/` -- Hugo templates for new pages (`default.md`, `concept.md`, `tutorial.md`, `landing-page.md`) -- `layouts/shortcodes/` -- Custom Hugo shortcodes for product versions and special formatting -- `static/` -- Static assets (images, scripts) organized by product -- `documentation/` -- Internal process docs - -## Creating new content - -Use Hugo archetypes to scaffold new documentation: - -```bash -# Default how-to guide -hugo new content nic/how-to/configure-ssl.md - -# Specific archetype -hugo new content ngf/concepts/routing.md -k concept -``` - -Front matter structure: - -```yaml -title: "Page title" # Sentence case; how-to/tutorial: verb phrase; concept: noun phrase -description: "One sentence summarizing the page, under 160 characters." -weight: 100 # Controls sort order, increments of 100 -toc: false # Enable for large documents (tech-specs, tutorial) -f5-product: F5 NGINX Ingress Controller # Use a name from the Product Names list below -f5-content-type: how-to # how-to | concept | reference | tech-specs | tutorial | getting-started | installation-guide | release-notes -f5-docs: DOCS-000 # Jira ticket ID for the doc request -f5-keywords: "keyword1, keyword2, keyword3" -f5-summary: > - Sentence 1: what the page covers. - Sentence 2: why it matters to the reader. - Sentence 3 (optional): scope or constraints. -f5-audience: any # developer | operator | admin | architect | any -``` - -When adding or updating `f5-product` in front matter, always use a name from -the **Product names** list at the end of this file. Do not invent codes or other names. - -## Hugo shortcodes and includes - -### Include files -```markdown -{{< include "nic/kubernetes-terminology.md" >}} -{{< include "waf/install-selinux-warning.md" >}} -``` - -- Only use includes for content appearing in 2 or more locations -- Do not include headings -- they won't appear in the TOC -- Do not nest includes unless unavoidable -- Keep include files context-agnostic and modular - -### Call-outs -```markdown -{{< call-out class="note" title="Note" >}} Text here. {{< /call-out >}} -{{< call-out class="warning" title="Warning" >}} Text here. {{< /call-out >}} -{{< call-out class="caution" >}} Text here. {{< /call-out >}} -``` - -Refer to the admonitions topic in the style guide for when to use each type. - -### Internal links -Always use the ref shortcode with absolute paths and file extensions: - -```markdown -[link text]({{< ref "/nic/deploy/install.md" >}}) -[section anchor]({{< ref "/integration/thing.md#section" >}}) -``` - -Never use relative links or bare markdown links for internal content. - -### Version shortcodes -```markdown -{{< nic-version >}} # NGINX Ingress Controller version -{{< version-ngf >}} # NGINX Gateway Fabric version -{{< version-waf >}} # WAF version -``` - -## Git workflow - -### Branch naming - -```text -/ -docs/ # for repo or non-product changes - -Examples: - nic/update-helm-links - ngf/add-tcp-routing-guide - docs/improve-contributing-guide -``` - -Release branches: `-release-` (for example, `agent-release-2.2`) - -### Commit messages (Conventional Commits) - -```text -: - - -``` - -Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore` - -Example: - -```text -feat: Add TLS passthrough guide for NGF - -This commit adds a new how-to guide for configuring TLS passthrough -in NGINX Gateway Fabric. The guide covers: - -- Prerequisites and Gateway API requirements -- Step-by-step configuration with examples -- Common troubleshooting scenarios - -Relates to issue #1234 -``` - -### Pre-commit hooks (optional) -```bash -pip install pre-commit -pre-commit install # enables gitlint and markdownlint-cli2 -``` - -## Linting - -- `.markdownlint.yaml` -- Markdown rules (headings, spacing, alt text) -- `.pre-commit-config.yaml` -- Git hooks (gitlint, markdownlint-cli2) - -Key markdownlint rules enforced: -- MD022/MD031/MD032: Blank lines around headings, code blocks, lists -- MD026: No trailing punctuation in headings -- MD045: All images must have alt text - -## Testing - -Playwright tests in `tests/`: - -```bash -cd tests -npm install -npx playwright test -``` - -## Hugo module system - -```bash -hugo mod get -u github.com/nginxinc/nginx-hugo-theme/v2 # Update theme -hugo mod tidy # Clean dependencies -``` - -Permalinks for products are defined in `config/_default/config.toml`. - -## Directory organization - -- Product content: `content//
/.md` -- Sections use `_index.md` with `weight:` to control nav ordering (increments of 100) -- Landing pages use the `landing-page` archetype -- Static assets mirror content structure: `static//images/` - -## Product names - -- F5 NGINX Agent -- F5 NGINX Gateway Fabric -- F5 NGINX Ingress Controller -- F5 NGINX Instance Manager -- F5 WAF for NGINX -- F5 DoS for NGINX -- F5 NGINXaaS -- F5 NGINXaaS for Azure -- F5 NGINXaaS for Google Cloud -- F5 NGINX One Console -- F5 NGINX Plus - -## Common pitfalls - -- Never use relative links -- always use `{{< ref "absolute/path.md" >}}` -- Run `make hugo-update` before major work -- Don't create includes for single-use content -- Don't use product acronyms in user-facing text -- Don't commit directly to `main` -- always use feature branches -- Don't forget `weight:` values in front matter (causes unpredictable sorting) - -## Key reference files - -- `.style-guide/` -- F5 Technical Writing Style Guide (Git submodule) -- `documentation/hugo-content.md` -- Hugo content guidance -- `documentation/git-conventions.md` -- Git conventions -- `documentation/include-files.md` -- Include file guidance -- `CONTRIBUTING.md` -- Contributor guide \ No newline at end of file +Read `AGENTS.md` in the repository root in full before responding to any request in this repo. It is the authoritative instruction file for this repository. \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..dfe3547df --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,243 @@ +# F5 Tech Writer Agent + +## Agent instructions + +Before responding to any request in this repo, read `.style-guide/agent-instructions/f5-tech-writer-agent.md` in full. It defines your role, workflows (review, copy edit, draft from notes), the style guide and template locations, north stars, mandatory rules, and +citation format. Treat it as your primary instructions for this repo. + +The section below adds NGINX-specific context this repo needs beyond the agent instructions. Everything below builds on those instructions -- it does not override them. + +## Hugo includes + +Some docs use Hugo shortcodes to include content from other files, for example: + + {{< include file="path/to/file.md" >}} + +When you encounter an include shortcode in a file you are editing, read the +included file and review it for style issues as part of the same task. Apply +the same style rules to included files. List changes to included files +separately in your output, citing the filename. + +--- + +## Repo overview + +This is a Hugo-based documentation site for F5 NGINX products (NGINX Plus, +NGINX Ingress Controller, NGINX Gateway Fabric, WAF, Instance Manager, etc.). +Content is written in Markdown with Hugo shortcodes, transformed to HTML via +Hugo v0.152.2, using the custom theme `github.com/nginxinc/nginx-hugo-theme/v2`. + +## Build and dev commands + +```bash +# Update Hugo theme before starting work +make hugo-update + +# Local development server +make watch # http://localhost:1313 + +# Include draft content +make drafts + +# Build for production +make docs # outputs to public/ + +# Linting +make lint-markdown # markdownlint-cli2 +make link-check # markdown-link-check +``` + +## Content structure + +- `content/` -- Product documentation organized by product code (`nic/`, `ngf/`, `waf/`, `nim/`, `agent/`, etc.) +- `content/includes/` -- Reusable content fragments (for example, `content/includes/waf/terminology.md`) +- `archetypes/` -- Hugo templates for new pages (`default.md`, `concept.md`, `tutorial.md`, `landing-page.md`) +- `layouts/shortcodes/` -- Custom Hugo shortcodes for product versions and special formatting +- `static/` -- Static assets (images, scripts) organized by product +- `documentation/` -- Internal process docs + +## Creating new content + +Use Hugo archetypes to scaffold new documentation: + +```bash +# Default how-to guide +hugo new content nic/how-to/configure-ssl.md + +# Specific archetype +hugo new content ngf/concepts/routing.md -k concept +``` + +Front matter structure: + +```yaml +title: "Page title" # Sentence case; how-to/tutorial: verb phrase; concept: noun phrase +description: "One sentence summarizing the page, under 160 characters." +weight: 100 # Controls sort order, increments of 100 +toc: false # Enable for large documents (tech-specs, tutorial) +f5-product: F5 NGINX Ingress Controller # Use a name from the Product Names list below +f5-content-type: how-to # how-to | concept | reference | tech-specs | tutorial | getting-started | installation-guide | release-notes +f5-docs: DOCS-000 # Jira ticket ID for the doc request +f5-keywords: "keyword1, keyword2, keyword3" +f5-summary: > + Sentence 1: what the page covers. + Sentence 2: why it matters to the reader. + Sentence 3 (optional): scope or constraints. +f5-audience: any # developer | operator | admin | architect | any +``` + +When adding or updating `f5-product` in front matter, always use a name from +the **Product names** list at the end of this file. Do not invent codes or other names. + +## Hugo shortcodes and includes + +### Include files +```markdown +{{< include "nic/kubernetes-terminology.md" >}} +{{< include "waf/install-selinux-warning.md" >}} +``` + +- Only use includes for content appearing in 2 or more locations +- Do not include headings -- they won't appear in the TOC +- Do not nest includes unless unavoidable +- Keep include files context-agnostic and modular + +### Call-outs +```markdown +{{< call-out class="note" title="Note" >}} Text here. {{< /call-out >}} +{{< call-out class="warning" title="Warning" >}} Text here. {{< /call-out >}} +{{< call-out class="caution" >}} Text here. {{< /call-out >}} +``` + +Refer to the admonitions topic in the style guide for when to use each type. + +### Internal links +Always use the ref shortcode with absolute paths and file extensions: + +```markdown +[link text]({{< ref "/nic/deploy/install.md" >}}) +[section anchor]({{< ref "/integration/thing.md#section" >}}) +``` + +Never use relative links or bare markdown links for internal content. + +### Version shortcodes +```markdown +{{< nic-version >}} # NGINX Ingress Controller version +{{< version-ngf >}} # NGINX Gateway Fabric version +{{< version-waf >}} # WAF version +``` + +## Git workflow + +### Branch naming + +```text +/ +docs/ # for repo or non-product changes + +Examples: + nic/update-helm-links + ngf/add-tcp-routing-guide + docs/improve-contributing-guide +``` + +Release branches: `-release-` (for example, `agent-release-2.2`) + +### Commit messages (Conventional Commits) + +```text +: + + +``` + +Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore` + +Example: + +```text +feat: Add TLS passthrough guide for NGF + +This commit adds a new how-to guide for configuring TLS passthrough +in NGINX Gateway Fabric. The guide covers: + +- Prerequisites and Gateway API requirements +- Step-by-step configuration with examples +- Common troubleshooting scenarios + +Relates to issue #1234 +``` + +### Pre-commit hooks (optional) +```bash +pip install pre-commit +pre-commit install # enables gitlint and markdownlint-cli2 +``` + +## Linting + +- `.markdownlint.yaml` -- Markdown rules (headings, spacing, alt text) +- `.pre-commit-config.yaml` -- Git hooks (gitlint, markdownlint-cli2) + +Key markdownlint rules enforced: +- MD022/MD031/MD032: Blank lines around headings, code blocks, lists +- MD026: No trailing punctuation in headings +- MD045: All images must have alt text + +## Testing + +Playwright tests in `tests/`: + +```bash +cd tests +npm install +npx playwright test +``` + +## Hugo module system + +```bash +hugo mod get -u github.com/nginxinc/nginx-hugo-theme/v2 # Update theme +hugo mod tidy # Clean dependencies +``` + +Permalinks for products are defined in `config/_default/config.toml`. + +## Directory organization + +- Product content: `content//
/.md` +- Sections use `_index.md` with `weight:` to control nav ordering (increments of 100) +- Landing pages use the `landing-page` archetype +- Static assets mirror content structure: `static//images/` + +## Product names + +- F5 NGINX Agent +- F5 NGINX Gateway Fabric +- F5 NGINX Ingress Controller +- F5 NGINX Instance Manager +- F5 WAF for NGINX +- F5 DoS for NGINX +- F5 NGINXaaS +- F5 NGINXaaS for Azure +- F5 NGINXaaS for Google Cloud +- F5 NGINX One Console +- F5 NGINX Plus + +## Common pitfalls + +- Never use relative links -- always use `{{< ref "absolute/path.md" >}}` +- Run `make hugo-update` before major work +- Don't create includes for single-use content +- Don't use product acronyms in user-facing text +- Don't commit directly to `main` -- always use feature branches +- Don't forget `weight:` values in front matter (causes unpredictable sorting) + +## Key reference files + +- `.style-guide/` -- F5 Technical Writing Style Guide (Git submodule) +- `documentation/hugo-content.md` -- Hugo content guidance +- `documentation/git-conventions.md` -- Git conventions +- `documentation/include-files.md` -- Include file guidance +- `CONTRIBUTING.md` -- Contributor guide \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md index 83c0dbdcf..fa7994829 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,238 +1,2 @@ -# NGINX Documentation - -@.style-guide/agent-instructions/f5-tech-writer-agent.md - -## Hugo includes - -Some docs use Hugo shortcodes to include content from other files, for example: - - {{< include file="path/to/file.md" >}} - -When you encounter an include shortcode in a file you are editing, read the -included file and review it for style issues as part of the same task. Apply -the same style rules to included files. List changes to included files -separately in your output, citing the filename. - ---- - -## Repo overview - -This is a Hugo-based documentation site for F5 NGINX products (NGINX Plus, -NGINX Ingress Controller, NGINX Gateway Fabric, WAF, Instance Manager, etc.). -Content is written in Markdown with Hugo shortcodes, transformed to HTML via -Hugo v0.152.2, using the custom theme `github.com/nginxinc/nginx-hugo-theme/v2`. - -## Build and dev commands - -```bash -# Update Hugo theme before starting work -make hugo-update - -# Local development server -make watch # http://localhost:1313 - -# Include draft content -make drafts - -# Build for production -make docs # outputs to public/ - -# Linting -make lint-markdown # markdownlint-cli2 -make link-check # markdown-link-check -``` - -## Content structure - -- `content/` -- Product documentation organized by product code (`nic/`, `ngf/`, `waf/`, `nim/`, `agent/`, etc.) -- `content/includes/` -- Reusable content fragments (for example, `content/includes/waf/terminology.md`) -- `archetypes/` -- Hugo templates for new pages (`default.md`, `concept.md`, `tutorial.md`, `landing-page.md`) -- `layouts/shortcodes/` -- Custom Hugo shortcodes for product versions and special formatting -- `static/` -- Static assets (images, scripts) organized by product -- `documentation/` -- Internal process docs - -## Creating new content - -Use Hugo archetypes to scaffold new documentation: - -```bash -# Default how-to guide -hugo new content nic/how-to/configure-ssl.md - -# Specific archetype -hugo new content ngf/concepts/routing.md -k concept -``` - -Front matter structure: - -```yaml -title: "Page title" # Sentence case; how-to/tutorial: verb phrase; concept: noun phrase -description: "One sentence summarizing the page, under 160 characters." -weight: 100 # Controls sort order, increments of 100 -toc: false # Enable for large documents (tech-specs, tutorial) -f5-product: F5 NGINX Ingress Controller # Use a name from the Product Names list below -f5-content-type: how-to # how-to | concept | reference | tech-specs | tutorial | getting-started | installation-guide | release-notes -f5-docs: DOCS-000 # Jira ticket ID for the doc request -f5-keywords: "keyword1, keyword2, keyword3" -f5-summary: > - Sentence 1: what the page covers. - Sentence 2: why it matters to the reader. - Sentence 3 (optional): scope or constraints. -f5-audience: any # developer | operator | admin | architect | any -``` - -When adding or updating `f5-product` in front matter, always use a name from -the **Product names** list at the end of this file. Do not invent codes or other names. - -## Hugo shortcodes and includes - -### Include files -```markdown -{{< include "nic/kubernetes-terminology.md" >}} -{{< include "waf/install-selinux-warning.md" >}} -``` - -- Only use includes for content appearing in 2 or more locations -- Do not include headings -- they won't appear in the TOC -- Do not nest includes unless unavoidable -- Keep include files context-agnostic and modular - -### Call-outs -```markdown -{{< call-out class="note" title="Note" >}} Text here. {{< /call-out >}} -{{< call-out class="warning" title="Warning" >}} Text here. {{< /call-out >}} -{{< call-out class="caution" >}} Text here. {{< /call-out >}} -``` - -Refer to the admonitions topic in the style guide for when to use each type. - -### Internal links -Always use the ref shortcode with absolute paths and file extensions: - -```markdown -[link text]({{< ref "/nic/deploy/install.md" >}}) -[section anchor]({{< ref "/integration/thing.md#section" >}}) -``` - -Never use relative links or bare markdown links for internal content. - -### Version shortcodes -```markdown -{{< nic-version >}} # NGINX Ingress Controller version -{{< version-ngf >}} # NGINX Gateway Fabric version -{{< version-waf >}} # WAF version -``` - -## Git workflow - -### Branch naming - -```text -/ -docs/ # for repo or non-product changes - -Examples: - nic/update-helm-links - ngf/add-tcp-routing-guide - docs/improve-contributing-guide -``` - -Release branches: `-release-` (for example, `agent-release-2.2`) - -### Commit messages (Conventional Commits) - -```text -: - - -``` - -Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore` - -Example: - -```text -feat: Add TLS passthrough guide for NGF - -This commit adds a new how-to guide for configuring TLS passthrough -in NGINX Gateway Fabric. The guide covers: - -- Prerequisites and Gateway API requirements -- Step-by-step configuration with examples -- Common troubleshooting scenarios - -Relates to issue #1234 -``` - -### Pre-commit hooks (optional) -```bash -pip install pre-commit -pre-commit install # enables gitlint and markdownlint-cli2 -``` - -## Linting - -- `.markdownlint.yaml` -- Markdown rules (headings, spacing, alt text) -- `.pre-commit-config.yaml` -- Git hooks (gitlint, markdownlint-cli2) - -Key markdownlint rules enforced: -- MD022/MD031/MD032: Blank lines around headings, code blocks, lists -- MD026: No trailing punctuation in headings -- MD045: All images must have alt text - -## Testing - -Playwright tests in `tests/`: - -```bash -cd tests -npm install -npx playwright test -``` - -## Hugo module system - -```bash -hugo mod get -u github.com/nginxinc/nginx-hugo-theme/v2 # Update theme -hugo mod tidy # Clean dependencies -``` - -Permalinks for products are defined in `config/_default/config.toml`. - -## Directory organization - -- Product content: `content//
/.md` -- Sections use `_index.md` with `weight:` to control nav ordering (increments of 100) -- Landing pages use the `landing-page` archetype -- Static assets mirror content structure: `static//images/` - -## Product names - -- F5 NGINX Agent -- F5 NGINX Gateway Fabric -- F5 NGINX Ingress Controller -- F5 NGINX Instance Manager -- F5 WAF for NGINX -- F5 DoS for NGINX -- F5 NGINXaaS -- F5 NGINXaaS for Azure -- F5 NGINXaaS for Google Cloud -- F5 NGINX One Console -- F5 NGINX Plus - -## Common pitfalls - -- Never use relative links -- always use `{{< ref "absolute/path.md" >}}` -- Run `make hugo-update` before major work -- Don't create includes for single-use content -- Don't use product acronyms in user-facing text -- Don't commit directly to `main` -- always use feature branches -- Don't forget `weight:` values in front matter (causes unpredictable sorting) - -## Key reference files - -- `.style-guide/` -- F5 Technical Writing Style Guide (Git submodule) -- `documentation/hugo-content.md` -- Hugo content guidance -- `documentation/git-conventions.md` -- Git conventions -- `documentation/include-files.md` -- Include file guidance -- `CONTRIBUTING.md` -- Contributor guide \ No newline at end of file +@AGENTS.md +@.style-guide/agent-instructions/f5-tech-writer-agent.md \ No newline at end of file diff --git a/opencode.json b/opencode.json new file mode 100644 index 000000000..cff1870e5 --- /dev/null +++ b/opencode.json @@ -0,0 +1,4 @@ +{ + "$schema": "https://opencode.ai/config.json", + "instructions": [".style-guide/agent-instructions/f5-tech-writer-agent.md"] +}