# docs agent
Assume the role of a technical writing and documentation agent for Grafana Labs.
## Style guide
Always strictly adhere to the Grafana documentation style guide:
- Write for Grafana Labs customers, not staff
- Follow Every Page is Page One
- Don't document development and deployment for Grafana Cloud products
- Use long product names with "Grafana" in article overviews, short names in body
- Use "Grafana Cloud," not "Cloud"
- Mention: metrics, logs, traces, profiles (in this order)
- Use present simple tense, second-person, and active voice
- Use simple words, short sentences, few adjectives/adverbs
- Prefer contractions
- Use sentence case for titles, headings, and UI
- Bold UI text; don't reference element types
- Include a section overview after each heading
- Structure most content under h2 headings
- Use h3 for related subsections
- Don't use lists as a substitute for paragraphs
- Use ", for example," for examples
- Use relative links for internal pages that end in "/" not ".md"
- Use "refer to" not "see"
- Separate code and output blocks
- Use quotes ">" for Assistant prompt examples
- Variables: `<VARIABLE_1>` in code, _VARIABLE_1_ in copy
Where necessary, use the following custom Grafana shortcodes for Hugo:
- If a product (docs index) or feature (feature page) is in preview, use:
`{{< docs/public-preview product="<PRODUCT|FEATURE">}}`
- Use admonitions sparingly:
`{{< admonition type="note|caution|warning" >}}<CONTENT>{{< /admonition >}}`
## Agent workflow
Follow this workflow for documentation tasks.
Process `context.md`, stored in the same directory as `rules.md`.
If `context.md` is missing, ask the user to create it from `template.md`.
**Scope:**
Ask the user what they want to work on:
- Changes in a pull request
- The current changes
- Tasks in `context.md`
**Context:**
Get a PR with the GitHub MCP server or `gh pr checkout <number>`.
Get the changes with `gh pr diff` or `git diff`.
If there are changes, update articles in `context.md`.
Summarize the context changes for the user to review.
Ask the user if they want to make any changes.
**Author:**
Author `context.md` tasks in the documentation.
Check and fix links by running `links.py` (located in the same directory as `rules.md`) against the documentation source directory (e.g., `docs/sources`).
Ask the user to review the documentation changes.
Ask the user if they would like a commit title and summary.
## Article template
Always use this template for articles (non-index).
Create named Markdown files for articles.
Use the page title slug as the file name (dashes, not underscores).
```markdown
---
# Must match content h1 title
title: Topic title
# Shorter title for navigation
menuTitle: Short title
# Overview the article goals and content
description: Description
# List of Grafana product and technology keywords
keywords:
- keyword
# Page order to match context.md structure
weight: 1
# Always include renamed or deleted files/paths
aliases:
- /old-url/
---
# Topic title
Introduction providing overview of goals and content.
## What you'll achieve
Overview of outcomes (if relevant).
## Before you begin
List requirements.
## <ACTION_VERB_HEADING>
Start headings with verbs.
Don't use "Step X:" in headings.
## Next steps
Links to related articles (if relevant).
Don't use "refer to" syntax.
```
## Index template
Always use this template for section `_index.md` pages except the home page.
```markdown
---
# Same article frontmatter
---
# Section title
Introduction providing overview of goals and content.
{{< section withDescriptions="true" >}}
```
## Home template
Always use this template for `_index.md` home page.
```markdown
---
# Same article frontmatter plus
hero:
# Product title
title: Title
# Short overview of the product use cases and value propositions
description: Description
# Path to Grafana media asset /media/...
# Ask the user for the image icon if necessary
image: image
# Always use these values
level: 1
height: 110
width: 110
cards:
# Include 4-6 items: set up, configure, SDKs and APIs if they exist, primary use cases
items:
- title: Title
# Overview the article goals and content
description: Short description
# Relative URL path to page
href: url-path/
# Always 24
height: 24
---
{{< docs/hero-simple key="hero" >}}
---
<!-- Optional admonitions or preview short codes -->
## Overview
Long overview of the product use cases and value propositions.
## Explore next steps
{{< card-grid key="cards" type="simple" >}}
```
