Skip to content

SKILL.md

Latest commit

 

History

History
1019 lines (704 loc) · 32.9 KB

SKILL.md

File metadata and controls

1019 lines (704 loc) · 32.9 KB
name doc-writer
description Guidelines for producing accurate and maintainable documentation for the Aspire documentation site. Use when writing or updating user guides, integration docs, tutorials, custom components used by docs, or documentation-related tests and validation on aspire.dev.

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.

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

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
  • Custom metadata as needed by Starlight theme

Required Imports

Import Starlight components at the top of your MDX file:

import { CardGrid, LinkCard, Steps, Tabs, TabItem, Icon, FileTree } from '@astrojs/starlight/components';

Additional commonly used imports:

import { Kbd } from 'starlight-kbd/components';
import LearnMore from '@components/LearnMore.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.

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

Press F5 to start debugging.

```

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.

Pivot/PivotSelector

Use for programming language selection that persists across page:

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

For Aspire AppHost docs, use a single page-level PivotSelector with key="aspire-lang" when the surrounding section flow should switch as one unit. If a page would otherwise need multiple aspire-lang selectors, keep the page-level selector for the main flow and use synced Tabs/TabItem with syncKey='aspire-lang' for repeated language-specific examples later on the page.

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

<TabItem id='typescript' label='TypeScript'>
TypeScript 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.ts"
import { createBuilder } from './.modules/aspire.js';

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 (C# and TypeScript)

Aspire supports both C# AppHosts (AppHost.cs) and TypeScript AppHosts (apphost.ts). Documentation must treat both languages as first-class citizens. Never write AppHost or hosting-integration documentation with a C#-only bias.

Core Principles

  1. Always show both languages: Every AppHost-focused example or walkthrough must include both C# and TypeScript variants unless the feature is genuinely language-specific.
  2. Use neutral framing: Write prose that applies to both languages. Say "In your AppHost" not "In your C# project". Say "Add a Redis resource" not "Call builder.AddRedis()".
  3. Neither language is the default: Don't present C# first as the "real" example and TypeScript as an afterthought. Both tabs are equal peers.
  4. Verify TypeScript APIs exist: Before writing a TypeScript example, confirm the API exists in the TypeScript AppHost SDK. Do not invent TypeScript samples — if you are unsure whether an API is available, flag it for review.

AppHostLangPivot Pattern for AppHost Content

Use AppHostLangPivot for AppHost-specific content that changes between C# and TypeScript. The component is controlled by the site-wide AppHost selector in the sidebar, so it should be the default choice for AppHost walkthroughs, code samples, and prose that should switch together.

import AppHostLangPivot from '@components/AppHostLangPivot.astro';

<AppHostLangPivot>
  <div slot="csharp">

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

var cache = builder.AddRedis("cache");

builder.AddProject<Projects.Api>("api")
    .WithReference(cache);

builder.Build().Run();
```

  </div>
  <div slot="typescript">

```typescript title="apphost.ts"
import { createBuilder } from './.modules/aspire.js';

const builder = await createBuilder();

const cache = await builder.addRedis("cache");

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

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

  </div>
</AppHostLangPivot>

Use AppHostLangPivot for more than code blocks when needed. Entire paragraphs, lists, asides, or multi-step sections can live inside the csharp and typescript slots when the workflows differ. The pivot itself is the shared wrapper; the slot names are the language discriminator.

Use Tabs for other concerns such as CLI vs IDE, deployment targets, or platform choices. Do not use Tabs syncKey="apphost-lang" for new AppHost content.

If a section heading should appear in the On this page table of contents, keep that heading outside AppHostLangPivot. Headings inside the csharp and typescript slots can be missed by the TOC generator, so the recommended pattern is a shared heading followed by an AppHostLangPivot containing only the language-specific body content.

Conventions

Aspect C# TypeScript
File title title="AppHost.cs" title="apphost.ts"
Pivot wrapper Shared AppHostLangPivot container Shared AppHostLangPivot container
Language slot slot="csharp" slot="typescript"
Builder creation DistributedApplication.CreateBuilder(args) import { createBuilder } from './.modules/aspire.js'; then newline for space followed by await createBuilder();
Method casing PascalCase (AddRedis) camelCase (addRedis)
Async pattern Synchronous fluent calls await each builder call
Build & run builder.Build().Run() await builder.build().run()

Prose Guidelines

When writing narrative text around AppHost examples:

  • ✅ "Add a Redis resource to your AppHost"
  • ✅ "The following example shows how to configure a PostgreSQL resource"
  • ❌ "Call builder.AddRedis() in your Program.cs" (C#-specific)
  • ❌ "Add the following C# code to your AppHost" (when both languages should be shown)

When a concept differs between languages (e.g., configuration files, async patterns), explain both within the AppHostLangPivot slots or in language-neutral prose above the pivot.

When TypeScript Is Not Yet Supported

If a hosting integration does not yet have TypeScript AppHost support, show only the C# example without AppHostLangPivot and add a note:

<Aside type="note">
TypeScript AppHost support for this integration is not yet available.
</Aside>

Do not wrap a single language in AppHostLangPivot or a single-language <Tabs> component — that creates a misleading UI suggesting another option exists.

Integration Documentation

File Location

Place integration docs in the appropriate category folder under src/frontend/src/content/docs/integrations/:

Category Folder Examples
AI/ML ai/ Ollama, Azure OpenAI
Caching caching/ Redis, Garnet, Valkey
Cloud cloud/ Azure, AWS services
Compute compute/ Docker, Kubernetes
Databases databases/ PostgreSQL, SQL Server, MongoDB
Frameworks frameworks/ Python, Rust, Orleans
Messaging messaging/ RabbitMQ, Kafka
Observability observability/ OpenTelemetry, Prometheus
Reverse Proxies reverse-proxies/ YARP
Security security/ Keycloak

Integration Documentation Structure

For Hosting-Only Integrations

---
title: [Technology] integration
description: Learn how to use the [Technology] integration with Aspire.
---

import { Aside } from '@astrojs/starlight/components';
import AppHostLangPivot from '@components/AppHostLangPivot.astro';
import InstallPackage from '@components/InstallPackage.astro';
import Image from 'astro:assets';

import techIcon from "@assets/icons/technology.svg";

<Image src={techIcon} alt="Technology logo" width={100} height={100} style="float: left; margin-right: 1rem;" data-zoom-off />

Brief description of the technology and what the integration enables.

## Hosting integration

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

### Add [Technology] resource

<AppHostLangPivot>
  <div slot="csharp">

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

var tech = builder.AddTechnology("tech");

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

  </div>
  <div slot="typescript">

```typescript title="apphost.ts"
import { createBuilder } from './.modules/aspire.js';

const builder = await createBuilder();

const tech = await builder.addTechnology("tech");

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

  </div>
</AppHostLangPivot>

### Configuration options

Describe available configuration methods and options.

## See also

- [Official Technology documentation](https://...)
- [Related Aspire documentation](/path/to/related/)

For Hosting + Client Integrations

Include both hosting and client sections:

## Hosting integration

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

### Add [Technology] resource

<AppHostLangPivot>
  <div slot="csharp">

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

var tech = builder.AddTechnology("tech");

builder.AddProject<Projects.Api>("api")
    .WithReference(tech);

builder.Build().Run();
```

  </div>
  <div slot="typescript">

```typescript title="apphost.ts"
import { createBuilder } from './.modules/aspire.js';

const builder = await createBuilder();

const tech = await builder.addTechnology("tech");

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

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

  </div>
</AppHostLangPivot>

### Hosting integration health checks

[Health check information if applicable...]

## Client integration

<InstallDotNetPackage package="Aspire.Technology" />

### Add [Technology] client

```csharp title="C# — Program.cs"
builder.AddTechnologyClient("tech");
```

### Add keyed [Technology] client

```csharp title="C# — Program.cs"
builder.AddKeyedTechnologyClient("tech");
```

For more information, see [.NET dependency injection: Keyed services](https://learn.microsoft.com/dotnet/core/extensions/dependency-injection#keyed-services).

### Configuration

#### Connection strings

The connection name must match the resource name defined in the AppHost.

#### Configuration providers

```json title="JSON — appsettings.json"
{
  "Aspire": {
    "Technology": {
      "myconnection": {
        "Option1": "value"
      }
    }
  }
}
```

### Client integration health checks

[Health check information...]

### Observability and telemetry

[Logging and tracing information...]

## See also

- [Official documentation](https://...)

Community Toolkit Integrations

For integrations from the Aspire Community Toolkit, add the badge at the top:

import Badge from '@astrojs/starlight/components/Badge.astro';

<Badge text="⭐ Community Toolkit" variant="tip" size="large" />

Updating Navigation

After creating documentation, update the sidebar configuration:

Location

Edit src/frontend/config/sidebar/sidebar.topics.ts (or the appropriate topic file)

Adding Entries

Add entries to the appropriate section in alphabetical order:

{ label: "Technology Name", slug: "integrations/category/technology" }

For collapsed sections with children:

{
  label: "Technology Name",
  collapsed: true,
  items: [
    { label: "Overview", slug: "integrations/category/technology" },
    { label: "Advanced", slug: "integrations/category/technology-advanced" },
  ]
}

Update Integration Links

After adding integration documentation, run the update-integrations prompt to ensure the integration is indexed:

.github/prompts/update-integrations.prompt.md

Writing Style Guidelines

Voice and Tone

  • Use second person ("you") when addressing the reader
  • Use active voice ("Create a resource" not "A resource is created")
  • Use imperative mood for instructions ("Call the method" not "You should call the method")
  • Be concise but complete
  • Be professional but approachable

Terminology

Use consistent terminology throughout:

Preferred Avoid
Aspire .NET Aspire (except in formal/legal contexts)
AppHost App Host, app host
resource component (for AppHost resources)
integration connector, plugin

Inclusive Language

  • Use inclusive, accessible language
  • Avoid assumptions about the reader's background
  • Use gender-neutral pronouns (they/them) or rewrite to avoid pronouns
  • Avoid ableist language (e.g., "blind to", "crippled by")
  • Use people-first language when discussing disabilities
  • Do not frame .NET as the default and everything else as an exception. Avoid phrases such as non-.NET, other languages, or wording that treats Python, JavaScript, Go, or container-based apps as secondary scenarios.
  • When a section is really about a capability or execution model, name that directly instead of contrasting it with .NET. For example, prefer headings such as Pass connection information to app resources or Run applications directly on the host over .NET vs. non-.NET framing.
  • If specific runtimes matter, name them because the product behavior differs for them—not just as a find-and-replace for non-.NET. Otherwise, use positive, capability-based language such as multi-language apps, app resources, services built from Dockerfiles, or apps that consume environment variables directly.

International Considerations

  • Write dates as "January 15, 2025" not "1/15/25"
  • Specify time zones when referencing specific times
  • Use diverse, international examples
  • Avoid idioms and culturally-specific references

Icons and Images

Icon Location

Place icons in src/frontend/src/assets/icons/

Icon Usage

import Image from 'astro:assets';
import techIcon from "@assets/icons/technology.svg";

<Image
    src={techIcon}
    alt="Technology logo"
    width={100}
    height={100}
    style="float: left; margin-right: 1rem;"
    data-zoom-off
/>

For light/dark theme variants:

import ThemeImage from '@components/ThemeImage.astro';

<ThemeImage
    lightSrc={techIconLight}
    darkSrc={techIconDark}
    alt="Technology logo"
    width={100}
    height={100}
/>

Terminal Recordings (Asciinema)

For details on terminal recordings, including how to create and embed them, see the terminal-recordings skill reference.

Testing Your Documentation

Before submitting documentation:

  1. Preview locally: Run the site locally to verify rendering and content flow
  2. Check links: Ensure all internal and external links work
  3. Validate code: Test all code examples compile and run using aspire run
  4. Review formatting: Verify components render correctly
  5. Run relevant tests: Do not consider documentation or component work done until the affected tests pass
  6. Check navigation: Confirm sidebar entries are correct

Documentation Validation Strategy

Use the smallest set of checks that proves the change is correct:

  • For MDX copy, structure, and navigation changes, verify the page locally and check the edited links.
  • For custom component usage changes, run the component render tests that cover the affected behavior.
  • For component prop surface changes, update and run the prop-contract coverage so editor completions and consumer typings stay intact.
  • For interactive behavior changes, run targeted Playwright coverage for the scenario you changed rather than relying on unrelated broad suites.
  • For accessibility-sensitive changes, validate both the rendered page and any focused accessibility tests that exercise the affected interaction.

Custom Component and Test Expectations

If a documentation change adds, removes, or materially changes a custom component, you should usually update one or more of these test layers:

  • src/frontend/tests/unit/custom-components.vitest.test.ts for runtime render coverage of custom Astro components.
  • src/frontend/tests/typecheck/component-props.contracts.ts when component props change and the public prop contract should remain typed for MDX and other consumers.
  • src/frontend/tests/e2e/*.spec.ts for user-visible interactions that depend on hydration, persistence, navigation, or accessibility behavior.

Examples of scenarios that often merit targeted tests:

  • query-string or local-storage persistence
  • cookie-consent or preference-driven behavior
  • responsive behavior that changes across desktop, tablet, and mobile
  • keyboard navigation, focus management, or screen-reader labeling
  • repeated code examples that need distinct accessible labels or titles
  • RSS, analytics, or other generated/static asset behaviors exposed through docs pages

Recommended Frontend Test Commands

Prefer targeted validation over the slowest possible full-site build when the change does not require it.

pnpm --dir ./src/frontend run test:unit:components
pnpm --dir ./src/frontend run test:unit:contracts
pnpm --dir ./src/frontend exec playwright test tests/e2e/<relevant-spec>.ts

If you changed custom components, docs interactions, or accessibility behavior, make sure the relevant targeted tests pass before submitting the work.

Installing the Aspire CLI

Ensure you have the appropriate version of the Aspire CLI installed for testing. The version depends on what you're documenting:

GA/Stable Builds (Default)

For documenting released features:

# Linux/macOS
curl -sSL https://aspire.dev/install.sh | bash

# Windows (PowerShell)
irm https://aspire.dev/install.ps1 | iex

For complete installation instructions, see Install Aspire CLI.

Nightly/Dev Builds

For documenting features on the main branch that haven't been released yet:

# Linux/macOS
curl -sSL https://aspire.dev/install.sh | bash -s -- --quality dev

# Windows (PowerShell)
iex "& { $(irm https://aspire.dev/install.ps1) } -Quality 'dev'"

You can also access this via the download icon on aspire.dev and selecting "Dev" from the Channel selector.

PR Builds

For documenting features in specific pull requests before they merge:

  1. Go to the PR in microsoft/aspire
  2. Find the build artifacts in the Checks/Actions section
  3. Download and install the CLI from the PR artifacts

This is useful for getting an early start on documentation for upcoming features.

Staging Builds

For prerelease builds from the current release branch:

# Linux/macOS
curl -sSL https://aspire.dev/install.sh | bash -s -- --quality staging

# Windows (PowerShell)
iex "& { $(irm https://aspire.dev/install.ps1) } -Quality 'staging'"

Running Locally

The documentation site can be run locally using the Aspire CLI:

aspire run
When testing code examples that add integration packages, use `aspire add ` rather than `dotnet add package`. The Aspire CLI automatically adds packages to the correct project.

Use the Aspire MCP tools to check the status of resources:

mcp_aspire_list_resources

Navigate to the frontend resource endpoint to view the documentation site.

Cross-Referencing

Link to Related Documentation

Use standard Markdown links with absolute paths from the docs root:

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

Reference NuGet Packages

Use the 📦 emoji with links:

Install the [📦 Aspire.Hosting.Redis](https://nuget.org/packages/Aspire.Hosting.Redis) package.

See Also Sections

End pages with a "See also" section linking to:

  • Official technology documentation
  • Related Aspire documentation
  • NuGet package pages
  • GitHub repositories (when applicable)

Localization

The aspire.dev site supports multiple languages. When creating new content:

  1. Create content in the default (English) location first
  2. Localized versions are managed separately in their respective folders (e.g., fr/, de/, ja/)
  3. Do not manually translate content - follow the project's localization workflow

Common Patterns

Prerequisites Notes

<Aside type="note" title="Prerequisites">
Before continuing, ensure you have:
- [Installed the Aspire CLI](/get-started/install-cli/)
- [Completed the prerequisites](/get-started/prerequisites/)
</Aside>

Version-Specific Information

<Aside type="caution">
This feature requires Aspire version 9.0 or later.
</Aside>

Feature Flags or Experimental Features

<Aside type="danger" title="Experimental">
This feature is experimental and may change in future releases.
</Aside>

Mermaid Diagrams

The site supports Mermaid diagrams for architecture visualization:

```mermaid
architecture-beta
  service api(logos:dotnet)[API service]
  service frontend(aspire:blazor)[Blazor front end]

  frontend:L --> R:api
```

Use the architecture-beta diagram type for service architecture diagrams.

Common Documentation Issues (From PR Feedback)

The following rules are derived from common feedback patterns in documentation PRs. Following these rules will help avoid common mistakes.

General Writing Rules

  1. Remove unnecessary commas: Don't write "Now, that you have..." - write "Now that you have..."
  2. Avoid casual language: Don't include phrases like "treat yourself to a coffee" or other informal asides in documentation
  3. Remove unused imports: Don't import components that aren't used in the document
  4. Verify all internal links: Links must point to pages that actually exist. Common mistakes:
    • Linking to /get-started/setup-and-tooling/ instead of /get-started/prerequisites/
    • Linking to /reference/cli/ for CLI installation instead of /get-started/install-cli/
  5. Add redirects when restructuring: When moving or renaming documentation pages, add redirect entries in src/frontend/config/redirects.mjs

Code Example Rules

  1. Use standard indentation: For fluent APIs on newlines, use standard 4-space indentation, NOT alignment with the method call above

    ✅ Correct:

    builder.AddProject<Projects.Api>("api")
    .WithReference(redis)
    .WithExternalHttpEndpoints();

    ❌ Incorrect (aligned indentation):

    builder.AddProject<Projects.Api>("api")
       .WithReference(redis)
       .WithExternalHttpEndpoints();

  2. Code block language identifiers: Use only one language identifier, not duplicates like csharp csharp

  3. Verify code syntax: Check for typos in code:

    • main:app not main.app (Python uvicorn module:app format)
    • Verify package/module names are correct

  4. Accurate technical descriptions:

    • process.env is an object, not a method
    • express is NOT used to access environment variables (that's process.env)
    • Don't claim libraries do things they don't do

  5. Connection string environment variables:

    • For C#/.NET: Use ConnectionStrings:resourcename (colon separator)
    • For Python/JavaScript: Use ConnectionStrings__resourcename (double underscore separator)
    • Use the standard ConnectionStrings__<resourcename> pattern, not custom variable names like ELASTICSEARCH_ENDPOINT

  6. Don't document deprecated APIs as primary examples: If an API is deprecated, don't use it as the first or main example. Use current, recommended APIs.

  7. Avoid insecure defaults in examples: Don't include TrustServerCertificate=true in connection strings without noting it's for development only

Component Usage Rules

  1. Match Pivot components to their PivotSelector: When using nested Pivot components, ensure they reference the correct parent PivotSelector with the key attribute

  2. Keep LinkCard descriptions concise: Card descriptions should be short enough to not squeeze the UI. Prefer "Configure persistence..." over "Discover how to configure persistence..."

  3. Avoid redundant Asides: Don't have two Asides saying similar things near each other

Cross-Language Documentation

When documenting integrations that support multiple languages (C#, Python, JavaScript):

  1. Show complete, working examples for each language
  2. Ensure variable names are defined before they're used in code examples
  3. Verify the same resource name is used consistently across language examples
  4. Don't remove code that defines variables that are used later in the document