Use this style guide when drafting, editing, or reviewing documentation for the agentgateway project.
- Product naming conventions
- Writing style
- Formatting with shortcodes
- Content structure
- Visuals
- Code examples
- Files and organization
Use sentence-case for agentgateway, such as:
- ✅ Agentgateway is...
- ✅ The agentgateway project is...
Do not use other variations, such as:
- ❌ Agent Gateway is...
- ❌ AgentGateway is...
- ❌ The Agentgateway project is...
- Active voice: "The gateway routes traffic" (not "Traffic is routed by the gateway").
- Present tense: "Istio provides mTLS" (not "Istio will provide mTLS").
- Second-person: "In this guide, you configure" (not "let's configure" or "we will configure").
- Conversational but technical: Explain "why" and "how it works", not just "what".
- No emojis in body text.
- Short sentences: Aim for 15-25 words per sentence.
- One idea per sentence: Complex ideas get multiple sentences.
- Paragraph length: 2-5 sentences per paragraph.
- Lists for enumeration: Use bullet points or numbered lists for 3+ items. Unless bullets are short (one or two words), punctuate them with a period.
- End sentences with the proper punctuation: Generally, end sentences with a period. If it is a question, end with a question mark. Use exclamation marks sparingly. Do not end sentences with a colon, unless it is a short phrase that introduces an immediate example, such as
Example output:. The first sentence after a heading that introduces steps should end with a period, not a colon.
-
First mention: Spell out acronyms with definition
**Mutual TLS (mTLS)** is a protocol where both client and server...
-
Subsequent mentions: Use acronym only
Configure mTLS for the control-to-data plane connection.
-
Avoid jargon: Explain technical concepts clearly
✅ "ztunnel is a node-level L4 proxy that handles TCP traffic" ❌ "ztunnel does L4 stuff"
When writing short descriptions, intros, or metadata, lead with the familiar term and alternative keywords that reflect the language people search for. Then, use our more declarative terms in the sentence. Incorporate the language into the sentence instead of listing alternatives in brackets.
Examples:
- "Use failover (also called automatic fallback) to keep services running..."
- "Set up cost controls, budgets, and spend limits..."
Places to put the terms:
- Page
description(front matter): Lead with the familiar term, then the action or outcome. Example: "Control cost with token budgets and spend limits to prevent unexpected bills and LLM misuse." - First paragraph or intro: Weave the discoverable term into the sentence after each heading. Example: "Get prompt logging, cost tracking, and an audit trail: review LLM-specific metrics, logs, and traces via OpenTelemetry."
- Card subtitles: Use the familiar language. Example: "Budget and spend limits" under Rate limiting.
Do not list every alternative in brackets. Do not mention specific products (such as Langfuse, LangSmith) in a description unless that page documents them.
The Hextra Hugo theme provides a set of shortcodes to style, format, and add content to your pages. For more information, see the Hextra Hugo theme documentation.
Important
Use GitHub-style alerts for notes, not the callout shortcode. Write > [!NOTE], > [!TIP], > [!IMPORTANT], > [!WARNING], or > [!CAUTION]. These render as styled alerts through the extras Goldmark extension, and they are already what most of these docs use. Convert a callout when you touch a page that has one. Every line of the body needs the > prefix, including blank lines between paragraphs, and an alert inside a numbered step must be indented to match the step.
cardsto format a collection of related links. Not for listing a section's own subpages — see Index pages.detailsto format a collapsible section of content.filetreeto format a directory file tree in a visually appealing way.iconused sparingly to add an icon inline.stepsused in tutorial pages only to style headings in a more visual way.tabsto present alternative ways within a step, such as for different modes, languages, load balancer vs localhost access, and so on.
This project has a few custom Hugo shortcodes that are used for content management.
link-hextrato link to a topic within the documentation in a way that is compatible with the versioning strategy.conditional-textto conditionally include text based on the current section of the docs (standalonefor the agentgateway binary orkubernetesfor agentgateway deployed on Kubernetes).glossto add a glossary term to the page.redirectto redirect a page to a different location within the doc set that has the same content. Useful for "placeholder" pages where we want the page to appear in several different sections in the navigation, but do not want to duplicate or reuse the content.reuseto include a piece of content from theassets/agw-docs/directory.versionto conditionally include text based on the current version. The versions for each section are defined in thehugo.yamlfile.
The docs have the following content types, although they are not strict.
- Concepts that explain key functionality and features of agentgateway. These are typically found in the
about/concepts/directory. They are typically written in a way that is easy to understand and follow. Include diagrams where appropriate. Usually do not include steps. - Reference pages that provide detailed information about certain agentgateway components such as Helm values or API docs. Most reference content is automatically generated from the code through the
reference-docsworkflow. These are typically found in thereference/directory. - FAQ page in the
faqs.mdfile that provides short answers to common questions about agentgateway. - Guides that provide the steps or procedure to accomplish a certain task. These are typically found in the rest of the directories. Their layout is as follows in the next section.
Content for guides typically follows a structure similar to the STYLE_EXAMPLE_PAGE.md file.
Every task heading in a guide has the same shape. Writing it in this order is what keeps a reader from having to backtrack.
- A short intro, two or three sentences: what this section does, why the reader does it, and how it fits the rest of the guide. Not a restatement of the heading.
- An ordered list of steps. One action per step, starting with an imperative verb. Each step carries its own context — what it does and why — in the same list item.
- An example in most steps: the command to run, or the configuration to apply.
- A field table under a configuration example, describing the fields the reader has to decide about. Every row must be findable in the example above it, because nesting is what a reader cannot guess:
spec.policies.authand a table row calledauthare not the same information. - Gotchas where they bite — in the field's table row, or in the step itself.
Expected output goes immediately under the command that produces it, truncated if it is long.
Do not put explanation in a note after the steps. This is the most common structural problem in these guides: the step says what to run, and a paragraph or a > [!NOTE] after the list explains what it did, which field matters, or what breaks. The reader already ran it. Move each of those:
| Found after the steps | Belongs |
|---|---|
| What the step accomplishes, or why it is needed | The first sentence of that step |
| What a field or flag in the example does | The field table under the example |
| A gotcha, limit, or version constraint on a setting | That field's table row, or the step |
| Something to know before running anything in the section | The section intro, above step 1 |
A trailing > [!NOTE] is right only where the information applies to the whole section and has no single step to live in.
A heading per action gives the reader a twenty-entry table of contents and hides how many actions the task really has. Group related actions into one numbered list under a heading that names the phase:
## Deploy the gateway <- a phase
1. Create the namespace.
2. Apply the Gateway resource.
3. Verify that the pod is running.Not:
### Create the namespace <- each of these is one step
### Apply the Gateway
### Verify the podKeep a heading only where a reader would reasonably link to or start from that point.
Agentgateway's primary color is #7734be.
Screenshots are used to illustrate the steps of a guide. They are typically found in the assets/agw-docs/img/ directory. Use sparingly, as these must be updated as the UI changes.
Use Mermaid to create diagrams. The most common diagram types are flowcharts and sequences. For more information and syntax, see the Mermaid documentation.
For more complex diagrams, we sometimes use Excalidraw.
General diagram principles:
- Include alt text context in surrounding prose
- Don't rely solely on color: Use labels and shapes too
- Describe flow in text: "The diagram shows traffic flowing from client → gateway → service"
- Use the primary color:
#7734befor the primary color.
Complete and valid:
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: example-route
namespace: default # Always include namespace
spec:
parentRefs:
- name: my-gateway
hostnames:
- "example.com"
rules:
- matches:
- path:
type: PathPrefix
value: /api
backendRefs:
- name: backend-service
port: 8080Key requirements:
- Valid YAML syntax: No syntax errors
- Realistic scenarios: Production-like configurations
- Complete examples: Don't omit required fields
- Namespace explicit: Always show
metadata.namespace - Comments inline: Explain non-obvious settings
Comment style:
spec:
parentRefs:
- name: my-gateway # References the Gateway this route attaches to
hostnames:
- "api.example.com" # Must match Gateway listener hostname
rules:
- matches:
- path:
type: PathPrefix # Matches /api, /api/v1, /api/v2, etc.
value: /apiBreak up long commands into multiple lines.
helm upgrade -i agentgateway-crds oci://ghcr.io/kgateway-dev/charts/agentgateway-crds \
--create-namespace \
--namespace agentgateway-system \
--version v{{< reuse "agw-docs/versions/n-patch.md" >}}Show expected output when helpful:
$ kubectl get gateways -A
NAMESPACE NAME CLASS ADDRESS READY
default my-gateway agentgateway 10.0.0.5 True- Lowercase with hyphens:
api-gateway-concepts.md(notAPI_Gateway_Concepts.md) - Descriptive: Name should indicate content
- Short but clear: 2-5 words ideal
- No special characters: Only
a-z,0-9, and-
The main content is organized into sections for the different deployment types. Each section has versioned subdirectories for the different versions of the documentation.
Often, the content pages consist of just the front matter for the page and a reuse shortcode that calls content from the assets/agw-docs/ directory. This is done for reuse across product sections and versions.
content/docs/
├── kubernetes/
│ ├── latest/
│ │ ├── index.md
│ │ ├── about/
│ │ ├── agent/
...
│ ├── main/
│ │ ├── index.md
│ │ ├── about/
│ │ ├── agent/
...
├── standalone/
│ ├── latest/
│ │ ├── index.md
│ │ ├── about/
│ │ ├── agent/
...
│ ├── main/
│ │ ├── index.md
│ │ ├── about/
│ │ ├── agent/
Every directory MUST have an _index.md file. Give it front matter and a brief description of the collection, and stop there.
Do not add a cards shortcode listing the subpages. The theme already renders a card grid of a section's children at the end of every _index.md, from docs-theme-extras's layouts/docs/list.html and its auto-section-cards.html partial. That grid reads each child's title, icon, and description, and sorts by weight.
A hand-written grid does not replace the generated one, it publishes a second copy of it. The partial documents a hasManualCards suppression flag, but the cards shortcode never sets it, so both grids ship. You can see this today on /docs/standalone/latest/observability/, which serves two card grids.
To change what the reader sees, edit the children, not the index:
| To change | Edit |
|---|---|
| What a card says | The child page's title and description |
| Card order | weight on the children |
| Whether a child appears | hidden: true on that child |
| The icon | icon on the child |
Two manual grids on an _index.md are still correct, because neither duplicates the children:
- A related-resources grid under its own heading, linking to a blog post, a video, or a page in another section.
- An
_index.mdwith no children. The partial renders nothing for an empty section, so hand-written links are the only navigation.
The test is never "does this _index.md contain cards". It is "does every card point at a child of this section?" If yes, delete the grid. If no, leave it alone.