Documentation lives in docs/, uses GitHub-flavored Markdown, renders with Astro Starlight, and follows Diátaxis.
Organize documentation into four Diátaxis types:
Purpose: Guide beginners through achieving a specific outcome to build confidence.
Avoid: Explaining concepts in depth, multiple options, troubleshooting
Purpose: Show how to solve a specific real-world problem or accomplish a particular task.
Avoid: Teaching fundamentals, explaining every detail, being exhaustive
Purpose: Provide accurate, complete technical descriptions of the system.
Avoid: Instructions, tutorials, opinions on usage
Purpose: Clarify and illuminate topics to deepen understanding.
Avoid: Step-by-step instructions, exhaustive reference material
aw for agentic workflow snippets with YAML frontmatterExample workflow code block:
on: push
# Your workflow steps here
Documentation files use GitHub-flavored markdown with Astro Starlight for rendering. Key syntax elements:
Every documentation page must have frontmatter:
title: Page Title
description: Brief description for SEO and navigation
Use GitHub's alert syntax for notes, tips, warnings, and cautions:
> [!NOTE]
> Important information the reader should notice.
> [!TIP]
> Helpful advice for the reader.
> [!WARNING]
> Warning about potential issues or pitfalls.
> [!CAUTION]
> Critical warning about dangerous operations.
> [!IMPORTANT]
> Key information users need to know.
title attribute for file names: ```yaml title=".github/workflows/example.yml"aw language for agentic workflow files with YAML frontmatterwrap for line wrapping: ```aw wrapUse tabs for showing alternatives (e.g., different languages, platforms):
import { Tabs, TabItem } from '@astrojs/starlight/components';
<Tabs>
<TabItem label="npm">
```bash
npm install package
```
</TabItem>
<TabItem label="yarn">
```bash
yarn add package
```
</TabItem>
</Tabs>
Use cards for navigation or highlighting multiple options:
import { Card, CardGrid } from '@astrojs/starlight/components';
<CardGrid>
<Card title="Getting Started" icon="rocket">
Quick introduction to the basics.
</Card>
<Card title="Advanced Usage" icon="setting">
Deep dive into advanced features.
</Card>
</CardGrid>
Remember: Keep components minimal. Prefer standard markdown when possible.
Documentation bloat reduces clarity and makes content harder to navigate. Common types of bloat include:
When editing documentation, focus on:
Consolidate bullet points:
Eliminate duplicates:
Condense verbose text:
Standardize structure:
Simplify code samples:
Before (Bloated):
### Tool Name
Description of the tool.
- **What it does**: This tool does X, Y, and Z
- **Why it's valuable**: It's valuable because A, B, and C
- **How to use**: You use it by doing steps 1, 2, 3, 4, 5
- **When to use**: Use it when you need X
- **Benefits**: Gets you benefit A, benefit B, benefit C
- **Learn more**: [Link](url)
After (Concise):
### Tool Name
Description of the tool that does X, Y, and Z to achieve A, B, and C.
Use it when you need X by following steps 1-5. [Learn more](url)
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).