Skip to content

Latest commit

 

History

History
315 lines (232 loc) · 14.4 KB

STYLE_GUIDE.md

File metadata and controls

315 lines (232 loc) · 14.4 KB

Style Guide

Use this style guide when drafting, editing, or reviewing documentation for the agentgateway project.

Table of contents

  1. Product naming conventions
  2. Writing style
  3. Formatting with shortcodes
  4. Content structure
  5. Visuals
  6. Code examples
  7. Files and organization

Product naming conventions

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...

Writing style

Voice and tone

  • 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.

Sentence structure

  • 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.

Technical terms

  • 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"

SEO-friendly terminology

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.

Formatting with shortcodes

Hextra Hugo theme shortcodes to style, format, and add content

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.

  • cards to format a collection of related links. Not for listing a section's own subpages — see Index pages.
  • details to format a collapsible section of content.
  • filetree to format a directory file tree in a visually appealing way.
  • icon used sparingly to add an icon inline.
  • steps used in tutorial pages only to style headings in a more visual way.
  • tabs to present alternative ways within a step, such as for different modes, languages, load balancer vs localhost access, and so on.

Custom Hugo shortcodes

This project has a few custom Hugo shortcodes that are used for content management.

  • link-hextra to link to a topic within the documentation in a way that is compatible with the versioning strategy.
  • conditional-text to conditionally include text based on the current section of the docs (standalone for the agentgateway binary or kubernetes for agentgateway deployed on Kubernetes).
  • gloss to add a glossary term to the page.
  • redirect to 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.
  • reuse to include a piece of content from the assets/agw-docs/ directory.
  • version to conditionally include text based on the current version. The versions for each section are defined in the hugo.yaml file.

Content structure

Content types

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-docs workflow. These are typically found in the reference/ directory.
  • FAQ page in the faqs.md file 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.

Standard page template

Content for guides typically follows a structure similar to the STYLE_EXAMPLE_PAGE.md file.

Anatomy of a task section

Every task heading in a guide has the same shape. Writing it in this order is what keeps a reader from having to backtrack.

  1. 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.
  2. 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.
  3. An example in most steps: the command to run, or the configuration to apply.
  4. 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.auth and a table row called auth are not the same information.
  5. 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.

Headings name phases, not steps

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 pod

Keep a heading only where a reader would reasonably link to or start from that point.

Visuals

Color palette

Agentgateway's primary color is #7734be.

Screenshots

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.

Diagrams

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: #7734be for the primary color.

Code examples

YAML standards

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: 8080

Key requirements:

  1. Valid YAML syntax: No syntax errors
  2. Realistic scenarios: Production-like configurations
  3. Complete examples: Don't omit required fields
  4. Namespace explicit: Always show metadata.namespace
  5. 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: /api

Bash examples

Break 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

Files and organization

File names

  • Lowercase with hyphens: api-gateway-concepts.md (not API_Gateway_Concepts.md)
  • Descriptive: Name should indicate content
  • Short but clear: 2-5 words ideal
  • No special characters: Only a-z, 0-9, and -

Directory structure

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/

Index pages

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.md with 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.