with one click
documentation
// Write concise Diataxis docs for gh-aw with Starlight markdown conventions.
// Write concise Diataxis docs for gh-aw with Starlight markdown conventions.
Route gh-aw workflow create/debug/upgrade requests to the right prompts.
Implement and test Go codemods for the gh aw fix command.
List GitHub repository labels with per_page pagination support.
List GitHub Actions workflows with per_page pagination support.
Write consistent, actionable validation error messages in gh-aw.
Format reports with HTML details/summary blocks for readable output.
| name | documentation |
| description | Write concise Diataxis docs for gh-aw with Starlight markdown conventions. |
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)