Doc Writer

Documentation Writer Skill

This skill provides guidelines for AI coding agents to help maintainers produce accurate and easy-to-maintain documentation for the Aspire project. The aspire.dev repository is the official documentation site for Aspire, and this skill helps ensure consistent, high-quality documentation.

When drafting or editing any document, follow the rules in the Common Documentation Issues reference.

When linking or referring to any other resource, follow the rules in the Cross-Referencing reference.

When drafting or editing documentation for an Aspire integration, use the file locations and documentation structures in the Integration Documentation reference.

Before finishing any draft, check it against the Prose Patterns skill reference.

Before finishing any draft, test it as described in the Testing Your Documentation reference.

Documentation Overview

Site Structure

Location: src/frontend/src/content/docs/
Audience: Developers using Aspire for cloud-native application development
Format: Astro with MDX files
Build System: Astro (static site generator with Starlight theme)

Documentation Categories

src/frontend/src/content/docs/
├── index.mdx                    # Landing page
├── get-started/                 # Getting started guides
│   ├── prerequisites.mdx
│   ├── install-cli.mdx
│   ├── first-app.mdx
│   └── ...
├── app-host/                    # AppHost documentation
├── architecture/                # Architecture concepts
├── dashboard/                   # Aspire Dashboard docs
├── deployment/                  # Deployment guides
├── diagnostics/                 # Diagnostics and telemetry
├── extensibility/               # Extensibility guides
├── fundamentals/                # Core concepts
├── integrations/                # Integration documentation
│   ├── ai/                      # AI integrations
│   ├── caching/                 # Caching integrations
│   ├── cloud/                   # Cloud integrations
│   ├── compute/                 # Compute integrations
│   ├── databases/               # Database integrations
│   ├── frameworks/              # Framework integrations
│   ├── messaging/               # Messaging integrations
│   ├── observability/           # Observability integrations
│   ├── reverse-proxies/         # Reverse proxy integrations
│   └── security/                # Security integrations
├── reference/                   # API reference
├── testing/                     # Testing guides
└── whats-new/                   # Release notes

Localization and Sidebar Labels

When adding, moving, or renaming localized docs pages, keep the sidebar topic config in sync under src/frontend/config/sidebar/*.topics.ts. Topic labels and item translations should include entries for the supported Starlight locale codes used by the site, such as pt-BR and zh-CN; do not add obsolete or generic locale keys like pt or pt-PT unless they are explicitly present in src/frontend/config/locales.ts.

Route path segments can be lowercase (pt-br, zh-cn), but sidebar translation keys follow the locale codes consumed by Starlight. API reference docs under src/content/docs/reference/api/ are intentionally not localized and should stay excluded from localization/sidebar translation work.

Astro and MDX Conventions

When calling pnpm dev or aspire run to test documentation in the context of CI/CD, or from an LLM, call astro telemetry disable to disable telemetry.

Frontmatter

Every documentation file requires frontmatter:

---
title: Page Title
description: A brief summary of the page content (required for SEO)
---

Optional frontmatter fields:

• next: false - Disable "Next page" link for terminal pages
• seoTitle - Override the page's og:title / twitter:title only, without touching the visible H1 or sidebar label. Use this only when the natural H1 must stay short (commands, terse labels). When set, the value is emitted verbatim — no · Aspire suffix is appended.
• Custom metadata as needed by Starlight theme

SEO length targets

The site uses Open Graph metadata to render social cards and feed SEO tooling. To keep previews scannable on every social network and to avoid the "title too short / description too long" lints that surface on Yoast, LinkedIn, and the search-console reports, follow these length targets when authoring frontmatter:

title becomes og:title composed as ${title} · Aspire, so the target window leaves room for the 9-character suffix. seoTitle overrides the composition outright — write the full string yourself.

Surface keywords from the article body itself in the description (verbs, integration names, API surfaces). The CI guard at tests/unit/seo-lengths.vitest.test.ts fails when any English page strays outside the wider 30-65 / 80-200 character guard ranges, so a draft can land slightly off-target and tighten in follow-ups.

Required Imports

Import Starlight components at the top of your MDX file, or custom components as needed:

import {
  CardGrid,
  LinkCard,
  Steps,
  Tabs,
  TabItem,
  Icon,
} from "@astrojs/starlight/components";
import FileTree from "starlight-plugin-icons/components/FileTree.astro";

Additional commonly used imports:

import { Kbd } from "starlight-kbd/components";
import LearnMore from "@components/LearnMore.astro";
import OsAwareTabs from "@components/OsAwareTabs.astro";
import PivotSelector from "@components/PivotSelector.astro";
import Pivot from "@components/Pivot.astro";
import ThemeImage from "@components/ThemeImage.astro";
import InstallPackage from "@components/InstallPackage.astro";
import InstallDotNetPackage from "@components/InstallDotNetPackage.astro";
import AsciinemaPlayer from "@components/AsciinemaPlayer.astro";
import Badge from "@astrojs/starlight/components/Badge.astro";
import { Image } from "astro:assets";

Component Usage

Prefer existing components in src/frontend/src/components/ over bespoke MDX markup when the site already has a reusable pattern for the content. This keeps docs consistent and reduces duplicated styling, accessibility fixes, and behavior logic.

When you introduce or change a custom component that is used by docs pages:

• Keep the public props intentional and typed so MDX authors get statement completion and editor help.
• Reuse existing aliases such as @components/* and @assets/* rather than deep relative imports.
• Prefer moving heavier shared logic into colocated .ts helpers when the .astro frontmatter becomes large or is duplicated across components.
• Treat user-visible behavior, accessibility, and responsive behavior as part of the documentation contract, not as optional polish.

Common Markdown syntax

Use the rendered examples in src/frontend/src/content/docs/community/contributor-guide.mdx as the canonical reference for common Markdown syntax. When adding tables, use padded pipes, a separator row with at least three hyphens per cell, and blank lines before and after the table:

| Feature | Description | Status |
| ------- | ----------- | ------ |
| Dashboard | Web-based monitoring | Available |

Do not replace standard Markdown with ad hoc HTML unless a component or layout requirement cannot be expressed clearly in Markdown.

Aside (Callouts)

Prefer fenced ::: callouts for tips, notes, cautions, and warnings. Use the Aside component only when a JSX-only composition pattern is required.

:::tip[Pro Tip]
This is a helpful tip for users.
:::

:::note
Important information users should be aware of.
:::

:::caution
Proceed with care - this may have unexpected consequences.
:::

:::danger
Critical warning - this could cause data loss or security issues.
:::

Steps

Use for sequential instructions:

<Steps>

1. First step with explanation

   ```bash title="Run this command"
   aspire new aspire-starter
   ```

2. Second step

3. Third step

</Steps>

Tabs/TabItem

Use for language or platform-specific content:

<Tabs syncKey="cli-commands">
<TabItem label="CLI">

```bash
aspire run
```

</TabItem>
<TabItem label="Visual Studio">

Press F5 to start debugging.

</TabItem>
</Tabs>
```

If a heading should appear in the On this page table of contents, keep that heading outside the Tabs component. Headings placed inside TabItem content may be skipped by the generated TOC.

OsAwareTabs (Bash and PowerShell)

When the only tab options are Bash and PowerShell, always use the OsAwareTabs custom component instead of bare <Tabs> / <TabItem>. OsAwareTabs wraps Starlight's synced Tabs and adds OS-aware behavior:

• Detects the reader's operating system and defaults the active tab to PowerShell on Windows and Bash everywhere else.
• Uses the canonical seti:shell and seti:powershell icons so the labels render consistently across the site.
• Persists the reader's choice across pages via the standard Starlight syncKey. Use syncKey="terminal" so all OS-aware terminal blocks stay in sync.
• Exposes two named slots — unix and windows — that contain the Bash and PowerShell content respectively.

import OsAwareTabs from "@components/OsAwareTabs.astro";

<OsAwareTabs syncKey="terminal">
<div slot="unix">

```bash
az group create --name my-group --location westus3
```

</div>
<div slot="windows">

```powershell
az group create --name my-group --location westus3
```

</div>
</OsAwareTabs>

A few rules to follow:

• Do not wrap a Bash + PowerShell pairing in bare <Tabs syncKey="shell-lang"> — convert it to OsAwareTabs instead. This is the canonical pattern used across the dashboard, install-cli, container-networking, and AKS deployment guides.
• Always set syncKey="terminal" unless there is a specific reason to scope the persistence differently. The site-wide convention is a single shared key so a reader who picks PowerShell once continues to see PowerShell on every page that offers the choice.
• Keep the leading and trailing blank lines around the inner code fences (as shown above). MDX requires the blank lines so the fenced code block is parsed correctly inside the slotted <div>.
• OsAwareTabs is only for the Bash + PowerShell pairing. Continue to use bare <Tabs> / <TabItem> for non-OS choices such as C#/TypeScript AppHost samples (syncKey='aspire-lang'), CLI vs IDE, deployment targets, or package managers.

Pivot/PivotSelector

Use Pivot and PivotSelector sparingly, only for key landing-page-style articles where the choice should persist across page navigations and where sharing the page through a URL should land the reader on a specific variant. Pivots support query string values to set the selected option (for example, ?aspire-lang=typescript). Examples in use today include the Build your first Aspire app and Deploy your first Aspire app tutorials.

For most pages — including AppHost C# and TypeScript code samples within a guide — prefer synced Tabs / TabItem blocks at the snippet level instead. See AppHost Language Parity (C# and TypeScript).

<PivotSelector
  title="Select your programming language"
  key="lang"
  options={[
    { id: "csharp", title: "C#" },
    { id: "python", title: "Python" },
  ]}
/>

<Pivot id="csharp">C# specific content here.</Pivot>

<Pivot id="python">Python specific content here.</Pivot>

If a heading needs to appear in the On this page table of contents, keep the heading outside the Pivot content and put only the variant-specific body content inside each Pivot.

On this page and "Overview" headings

When a page shows the On this page table of contents (the default behavior unless tableOfContents: false is set), do not add an Overview heading at any level (##, ###, etc.). The docs site already provides an implicit overview link to the top of the page, so an explicit Overview heading becomes redundant.

If your opening section is truly introductory, keep it as body copy without an Overview heading. If that section has a more specific purpose, use a descriptive heading such as Key concepts, Prerequisites, or another topic-specific label.

For Aspire AppHost code examples, use synced Tabs / TabItem blocks with syncKey='aspire-lang' at each code snippet. List TypeScript first so apphost.mts is the default experience for readers without a saved preference. Do not add a page-level PivotSelector just to switch AppHost code samples between TypeScript and C#. Readers should be able to switch the language at the specific snippet they are reading.

<Tabs syncKey='aspire-lang'>
<TabItem id='typescript' label='TypeScript'>
TypeScript example content here.
</TabItem>

<TabItem id='csharp' label='C#'>
C# example content here.
</TabItem>
</Tabs>

CardGrid and LinkCard

Use for navigation and feature highlights:

<CardGrid>
  <LinkCard
    title="Getting Started"
    description="Build your first Aspire app"
    href="/get-started/first-app/"
  />
  <LinkCard
    title="Integrations"
    description="Explore available integrations"
    href="/integrations/"
  />
</CardGrid>

Kbd (Keyboard Shortcuts)

Use the Kbd component from starlight-kbd to display keyboard shortcuts with OS-specific variants. This renders styled <kbd> elements and automatically shows the correct shortcut for the reader's operating system.

import { Kbd } from "starlight-kbd/components";

Open the Command Palette (<Kbd windows="Ctrl+Shift+P" mac="Cmd+Shift+P" />)

Props:

• windows — The shortcut for Windows (also used as the default/Linux fallback)
• mac — The shortcut for macOS
• linux — (optional) The shortcut for Linux, if different from Windows

You can specify just windows when the shortcut is the same on all platforms (e.g., <Kbd windows="F5" />), or provide OS-specific values when they differ:

Open a terminal (<Kbd windows="Ctrl+`" mac="⌘+`" linux="Ctrl+`" />)

Always prefer the Kbd component over the raw HTML <kbd> element, even for simple keys that don't vary by OS. This ensures consistent styling and behavior across the site:

Press <Kbd windows="F5" /> to start debugging.

LearnMore

Use the LearnMore component to add a styled "learn more" link with an open-book icon. It provides a consistent visual pattern for directing readers to related documentation.

import LearnMore from "@components/LearnMore.astro";

<LearnMore>
  For more information, see [Service Defaults](/fundamentals/service-defaults/).
</LearnMore>

The component renders an open-book icon alongside the provided content. Place it after a section or code example to point readers to deeper documentation. It works well inside fenced ::: callouts or after <Steps>:

:::tip[Feature flag]
Enable polyglot support by running:

```bash
aspire config set features:polyglotSupportEnabled true --global
```

<LearnMore>
  For more information, see [aspire config command
  reference](/reference/cli/commands/aspire-config-set/)
</LearnMore>
:::

Aspire Custom Components

Use Aspire's custom components when they express a documentation pattern more clearly than raw Markdown or ad hoc HTML. Common examples include LearnMore, PivotSelector, Pivot, ThemeImage, InstallPackage, InstallDotNetPackage, AsciinemaPlayer, and the other components in src/frontend/src/components/.

Before introducing a new custom component for docs:

• Check whether an existing component already solves the layout or interaction.
• Prefer extending an existing component when the semantics stay clear.
• Only add a new component when the pattern will be reused or the behavior is complex enough to justify a shared abstraction.

If you add or change a custom component, also update the relevant tests so documentation behavior stays covered.

Code Blocks

Always include a descriptive title:

```csharp title="AppHost.cs"
var builder = DistributedApplication.CreateBuilder(args);

var api = builder.AddProject<Projects.Api>("api");

// After adding all resources, run the app...
builder.Build().Run();
```

```typescript title="apphost.mts"
import { createBuilder } from "./.aspire/modules/aspire.mjs";

const builder = await createBuilder();

const api = await builder.addProject("api", "../Api/Api.csproj");

await builder.build().run();
```

For JSON configuration:

```json title="JSON — appsettings.json"
{
  "ConnectionStrings": {
    "mydb": "Host=localhost;Database=mydb"
  }
}
```

Package Installation Components

For hosting packages:

<InstallPackage package="Aspire.Hosting.Redis" />

For client/library packages:

<InstallDotNetPackage package="Aspire.StackExchange.Redis" />

AppHost Language Parity (TypeScript and C#)

Aspire supports both TypeScript AppHosts (apphost.mts) and C# AppHosts (AppHost.cs). Documentation must treat both languages as first-class citizens. Always show both TypeScript and C# code samples for AppHost code unless the feature is genuinely language-specific or TypeScript support does not exist yet. Never write AppHost or hosting-integration documentation with a C#-only bias.