Contributor guide for aspire.dev

Thank you for your interest in contributing to aspire.dev! Whether you’re fixing typos, adding new content, or improving existing pages, this guide will help you get started and your contributions are greatly appreciated.

🚀 About this site

This documentation site is built using Starlight, a full-featured documentation theme built on top of Astro. Starlight provides a fast, accessible, and SEO-friendly foundation, while Astro’s component-based architecture makes it easy to create and maintain content.

🤔 Ways to contribute

There are several ways you can contribute to aspire.dev:

• Small fixes - Correct typos, grammar mistakes, or formatting issues.
• Content additions - Add new documentation pages or sections to cover missing topics.
• Content improvements - Enhance existing documentation with clearer explanations, updated information, or additional examples.
• Code contributions - Improve the site’s codebase, fix bugs, or add new features.

There’s also different methods for contributing, from selecting the Edit page button at the bottom of any documentation page, to using GitHub Codespaces for a fully configured development environment, or setting up a local development environment on your machine.

Click-edit

Selecting the Edit page button at the bottom of any documentation page will take you to the corresponding file in the GitHub repository. From there, you can make changes directly in the GitHub web interface and submit a pull request. This is best suited for small fixes or minor content additions.

Tip

If you haven’t noticed the Edit page button, scroll to the bottom of this page and you should see it there:

Codespaces

To avoid local setup, you can use GitHub Codespaces for a fully configured development environment in the cloud. This is ideal for larger contributions or if you prefer not to set up a local environment.

Note

If you choose to use Codespaces, please still refer to the rest of this guide for information on writing style, code quality, and the contribution workflow. Continue reading at the Writing style section below.

Local development

If you prefer to work locally, you can set up a development environment on your machine. Follow the instructions below to get started.

📋 Prerequisites

Before you begin, ensure you have the following installed:

• Node.js (LTS version recommended) - For running the development server
• pnpm - Fast, disk space efficient package manager
• Visual Studio Code - Recommended code editor
• Git - For version control

⚙️ Local dev setup

1. Clone the aspire.dev repository.

   git clone https://github.com/microsoft/aspire.dev.git

2. Navigate to the aspire.dev directory.

   cd aspire.dev

3. Install dependencies

   pnpm

   pnpm install

   npm

   npm install

   Stop using npm

   If you’re not already using pnpm, consider switching! It’s faster and more efficient than npm or yarn.

   Install globally with:

   npm install -g pnpm

4. Run the development server

   pnpm dev

   This starts the Vite development server for the frontend and provide hot-reload capabilities.

5. View the site locally

   Open your browser to http://localhost:4321 (or the port shown in your terminal)

   Tip

   During local development, the site search functionality is disabled. This is normal behavior as the search index is built during the production build process. To test search functionality, run a production build locally using pnpm build and then preview it with pnpm preview.

Known formatting limitations

We expose lint and format scripts in the package.json to help maintain code quality and consistency. This isn’t something that you’re need to run manually. However, regardless of whether or not you run these scrips, be aware of the following known limitation when working with MDX files.

Achtung

Prettier and Steps components

The Prettier formatter has a known limitation when formatting MDX files containing the Steps component. Prettier incorrectly converts all ordered lists (ol) as a single line, which causes the steps to render malformed.

Workaround: Always ensure there is a blank line between each step item in a Steps component. For example:

<Steps>

1. First step with content

1. Second step with content

1. Third step with content

</Steps>

Without the blank lines between steps, the inner content won’t render correctly. If you notice steps appearing malformed after running pnpm format, manually add the blank lines back before committing.

➡️ Git workflow

1. Start from an issue (or a discussion that leads to an issue)

2. Fork the repository

   As mentioned in the local dev setup section, start by forking the aspire.dev repository to your own GitHub account

3. Create a new branch for your changes

   git checkout -b feature/your-feature-name

4. Make your changes, considering the writing style guide

5. Commit with descriptive messages

6. Push to your fork

7. Create a pull request, and always follow the Code of Conduct

✍️ Writing style guide

When contributing to aspire.dev, follow these writing guidelines to ensure consistency and clarity:

• Use clear and concise language - Aim for simplicity. Avoid jargon unless necessary, and explain technical terms when they first appear.
• Be consistent - Follow existing conventions in terminology, formatting, and structure. Refer to other documentation pages for examples.
• Use active voice - Write in active voice to make instructions and explanations more direct and engaging.
• Use sentence case - Capitalize only the first word and proper nouns in headings, sidebars, and table of contents.
• Be inclusive - Use inclusive language that respects all readers. Avoid gendered terms and stereotypes.
• Provide examples - Where applicable, include code snippets or examples to illustrate concepts.
• Use proper grammar and spelling - Proofread your contributions to ensure they are free of errors and typos.
• Structure content logically - Use headings, subheadings, and lists to organize information in a way that is easy to follow.
• Link to relevant resources - When mentioning concepts, tools, or related documentation, provide links to help readers find more information.
• Follow formatting conventions - Use consistent formatting for code snippets, commands, and technical terms. Refer to the examples in this guide for guidance.
• Review existing content - Before adding new content, review existing documentation to avoid duplication and ensure coherence.

AppHost-specific C# and TypeScript content

When you are documenting AppHost-specific content that changes between C# and TypeScript, add an in-page PivotSelector with the title Select your Aspire programming language, the key aspire-lang, and C# and TypeScript options. Pair it with Pivot blocks for the language-specific content.

Use Tabs for other choices such as package managers, deployment targets, IDEs, or CLI variants.

If a feature is only available in the C# AppHost today, show the C# example by itself and add an explanatory note. Do not add a language selector for a single-language example.

If the page already has another PivotSelector, stop and review the layout before adding a second selector. Those pages need a manual pass so the page does not end up with competing selector UIs.

For the On this page table of contents to pick up a heading reliably, define the heading outside Pivot and Tabs. Headings inside those components are often missed or can produce incomplete results in the generated table of contents.

📝 Write Markdown

Here are some common Markdown formatting examples to help you write documentation:

Frontmatter

You can customize individual pages in aspire.dev by setting values in their frontmatter. Frontmatter is set at the top of your files between --- separators:

src/content/docs/example.md

---
title: My page title
---

Page content follows the second `---`.

Every page must include at least a title. See the frontmatter reference for all available fields and how to add custom fields.

Headings

Use # symbols to create headings. More # symbols create smaller headings:

src/content/docs/example.md

## Heading 2
### Heading 3
#### Heading 4

Headings are automatically created as bookmarks (shareable deep links) for easy navigation.

Hinweis

Avoid using Heading 1 (#) in your content, as it is reserved for the page title defined in frontmatter.

Tipp

To configure which headings appear in the On this page sidebar, use the tableOfContents frontmatter field. See the tableOfContents reference for more details.

Text formatting

Bold text is created with double asterisks:

src/content/docs/example.md

**Bold text**

Italic text is created with an _ (or single asterisks *—while valid, for consistency we recommend using _):

src/content/docs/example.md

_Italic text_

Inline code is created with backticks:

src/content/docs/example.md

`Inline code`

Links

Links are created with square brackets and parentheses:

src/content/docs/example.md

[David Pine](https://davidpine.net)

Renders as:

David Pine

Additionally, when linking to other pages within aspire.dev, use site relative paths:

src/content/docs/example.md

[Build your first Aspire app](/get-started/first-app/)

Renders as:

Build your first Aspire app

Note

Site relative links should always include a trailing slash / at the end to ensure proper navigation.

This is confugred by default for aspire.dev, for more information see Astro Docs: trailingSlash.

Lists

Unordered lists use - (or *—while valid, for consistency we recommend using -):

src/content/docs/example.md

- First item
- Second item
- Third item

Renders as:

• First item
• Second item
• Third item

Ordered lists use numbers:

src/content/docs/example.md

1. First step
2. Second step
3. Third step

Renders as:

1. First step
2. Second step
3. Third step

Code blocks

Use triple backticks with a language identifier for syntax highlighting:

src/content/docs/example.md

```csharp title="C# — AppHost.cs"
var builder = DistributedApplication.CreateBuilder(args);
builder.AddProject<Projects.ApiService>("apiservice");
```

Renders as:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);
builder.AddProject<Projects.ApiService>("apiservice");

To add a title to a code block, use this syntax:

src/content/docs/example.md

```csharp title="Program.cs"
var builder = DistributedApplication.CreateBuilder(args);
builder.AddProject<Projects.ApiService>("apiservice");
```

Renders as:

Program.cs

var builder = DistributedApplication.CreateBuilder(args);
builder.AddProject<Projects.ApiService>("apiservice");

Blockquotes

Use > to create blockquotes:

src/content/docs/example.md

> This is a note or important callout.

Renders as:

This is a note or important callout.

Tables

Create tables using pipes | and hyphens -:

src/content/docs/example.md

| Feature | Description | Status |
|--|--|--|
| Dashboard | Web-based monitoring | ✅ Available |
| Telemetry | OpenTelemetry support | ✅ Available |
| Deployment | Kubernetes deployment | 🚧 Preview |

Renders as:

Feature	Description	Status
Dashboard	Web-based monitoring	✅ Available
Telemetry	OpenTelemetry support	✅ Available
Deployment	Kubernetes deployment	🚧 Preview

Tipp

You can align columns using colons: | :--- | for left, | :---: | for center, and | ---: | for right alignment.

Horizontal rules

Create a horizontal rule with three or more hyphens, asterisks, or underscores:

src/content/docs/example.md

---

Renders as:

---

Strikethrough

Use double tildes to create strikethrough text:

src/content/docs/example.md

~~This text is crossed out~~

Renders as:

This text is crossed out

Task lists

Create interactive task lists in Markdown:

- [x] Add Aspire to your project
- [x] Configure service defaults
- [ ] Deploy to Azure
- [ ] Set up monitoring

Renders as:

• Add Aspire to your project
• Configure service defaults
• Deploy to Azure
• Set up monitoring

Nested lists

You can nest lists by indenting with two spaces:

- Aspire components
  - Databases
    - PostgreSQL
    - Redis
  - Messaging
    - RabbitMQ
    - Azure Service Bus

Renders as:

• Aspire components
  • Databases
    • PostgreSQL
    • Redis
  • Messaging
    • RabbitMQ
    • Azure Service Bus

Escaping characters

Use a backslash \ to escape special Markdown characters:

\*This text is not italic\*
\[This is not a link\]

Renders as:

*This text is not italic* [This is not a link]

Line breaks

End a line with two or more spaces to create a line break:

First line with two spaces at the end
Second line

Or use an empty line to create a paragraph break.

➕ Markdown extensions

The aspire.dev site supports several Markdown extensions to enhance your documentation:

Mermaid diagrams

You can write mermaid diagrams as code blocks:

src/content/docs/example.md

```mermaid
graph TD
    A[build-apiservice] --> C[push-apiservice]
    B[provision-container-registry] --> C
    C --> D[deploy-apiservice]
    E[provision-cosmosdb] --> D
    F[provision-identity] --> D
```

Renders as:

graph TD
    A[build-apiservice] --> C[push-apiservice]
    B[provision-container-registry] --> C
    C --> D[deploy-apiservice]
    E[provision-cosmosdb] --> D
    F[provision-identity] --> D

Asides

Asides, “admonitions”, “callouts”, or “alerts” are special highlighted blocks used to draw attention to important information, tips, warnings, or notes.

The ::: syntax creates asides given a type of note, tip, caution, or danger in both Markdown and MDX:

Use the ::: syntax as the default pattern in aspire.dev docs, including .mdx pages. Prefer the Aside component only when you specifically need a JSX-only composition pattern that fenced callouts cannot express cleanly.

src/content/docs/example.md

:::note
Some content in an aside.
:::

:::caution
Some cautionary content.
:::

:::tip

Other content is also supported in asides.

```js
// A code snippet, for example.
```

:::

:::danger
Do not give your password to anyone.
:::

Renders as:

Note

Some content in an aside.

Caution

Some cautionary content.

Tip

Other content is also supported in asides.

// A code snippet, for example.

Danger

Do not give your password to anyone.

Additionally, aspire.dev supports GitHub Alerts syntax with the community plugin:

For example, you can write:

Note

src/content/docs/example.md

> [!NOTE]
> Useful information that users should know, even when skimming content.

Renders as:

Note

Useful information that users should know, even when skimming content.

See the full demo here: Starlight: GitHub Alerts.

If you need a JSX-only fallback, see the Aside component section below.

☑️ Write MDX

MDX files use the .mdx extension and combine standard Markdown with the power of JSX. This means you can write content and seamlessly embed interactive components—all in one file.

Learn more about MDX.

With the power of Astro components, you can enhance your documentation with interactive elements, custom layouts, and dynamic content. To use any of the built-in Starlight or custom components available in aspire.dev, simply import them at the top of your MDX file and use them like regular JSX components.

LinkButton component

src/content/docs/example.mdx

---
title: Example MDX Page
---

import { LinkButton } from '@astrojs/starlight/components';

Here's an example of an MDX page with a custom button:

<LinkButton href="https://aspire.dev" variant="primary">
  Visit aspire.dev
</LinkButton>

Renders as:

Here’s an example of an MDX page with a custom button:

Visit aspire.dev

For all available components, see: Starlight: Components.

Aside component

Prefer ::: callouts for new docs content. The Aside component from Starlight is the fallback option when you need JSX composition inside a callout:

src/content/docs/example.mdx

---
title: Example MDX Page
---

import { Aside } from '@astrojs/starlight/components';

<Aside>Some content in an aside.</Aside>

<Aside type="caution">Some cautionary content.</Aside>

<Aside type="tip">

  Other content is also supported in asides.

  ```js
  // A code snippet, for example.
  ```

</Aside>

<Aside type="danger">Do not give your password to anyone.</Aside>

Renders as:

Hinweis

Some content in an aside.

Achtung

Some cautionary content.

Tipp

Other content is also supported in asides.

// A code snippet, for example.

Gefahr

Do not give your password to anyone.

Using custom components

To use custom components available in aspire.dev, import them at the top of your MDX file. Custom component imports rely on configured aliases—have a look at the tsconfig.json file for more information:

JSON — tsconfig.json

{
  "extends": "astro/tsconfigs/strict",
  "include": [".astro/types.d.ts", "**/*"],
  "exclude": ["dist"],
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@assets/*": ["./src/assets/*"],
      "@components/*": ["./src/components/*"],
      "@data/*": ["./src/data/*"],
      "@tests/e2e/*": ["./tests/e2e/*"],
      "@tests/typecheck/*": ["./tests/typecheck/*"],
      "@tests/unit/*": ["./tests/unit/*"],
      "@tests/*": ["./tests/*"],
      "@utils/*": ["./src/utils/*"]
    }
  }
}

By using the @components alias, you can easily import any custom component from the frontend/src/components/ directory. For example, to import the LearnMore component used in this guide:

src/content/docs/example.mdx

---
title: Example MDX Page
---

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

Here's an example of using the `LearnMore` component:

<LearnMore>
  Please give our [repository a star on GitHub! ⭐](https://github.com/microsoft/aspire.dev)
</LearnMore>

Aspire language selectors

Use an in-page PivotSelector plus Pivot blocks when the surrounding AppHost content should switch between C# and TypeScript as a single unit.

If a page would otherwise need multiple PivotSelector controls with key="aspire-lang", do not repeat the selector. Keep the page-level PivotSelector for the main flow, and use synced Tabs and TabItem blocks for repeated language-specific examples instead.

Keep shared section headings outside the pivots or tabs. For example, write ## Add a Redis resource before the selector and the Pivot blocks, then place the language-specific prose and code inside the csharp and typescript pivots. This helps the On this page navigation stay accurate.

src/content/docs/example.mdx

---
title: Example MDX Page
---

import PivotSelector from '@components/PivotSelector.astro';
import Pivot from '@components/Pivot.astro';

<PivotSelector
  title="Select your programming language"
  key="aspire-lang"
  options={[
    { id: 'csharp', title: 'C#' },
    { id: 'typescript', title: 'TypeScript' },
  ]}
/>

<Pivot id="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();
  ```

</Pivot>
<Pivot id="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();
  ```

</Pivot>

Use this pattern when entire sections differ by AppHost language, not just a single code fence. For example, each Pivot can contain explanatory prose, steps, asides, and code blocks together.

For repeated language-specific code examples later on the same page, use synced tabs instead of adding another PivotSelector:

src/content/docs/example.mdx

import { Tabs, TabItem } from '@astrojs/starlight/components';

<Tabs syncKey='aspire-lang'>
<TabItem id='csharp' label='C#'>

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

</TabItem>
<TabItem id='typescript' label='TypeScript'>

```typescript title="apphost.ts"
const builder = await createBuilder();
await builder.addRedis("cache");
```

</TabItem>
</Tabs>

If the difference is not about AppHost language, keep using regular Tabs.

The same TOC rule applies to Tabs and Pivot: if a heading should appear in On this page, keep that heading outside the component and only put the variant-specific body content inside.

Renders as:

Here’s an example of using the LearnMore component:

Please give our repository a star on GitHub! ⭐

🆘 Getting help

• Issues - Report bugs or request features via GitHub Issues
• Discussions - Join conversations in GitHub Discussions
• Discord - Connect with the community on the Aspire Discord