Thank you for your interest in contributing toaspire.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.

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

There are several ways you can contribute toaspire.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 theEdit page button at the bottom of any documentation page, to usingGitHub Codespaces for a fully configured development environment, or setting up a local development environment on your machine.

Selecting theEdit 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 theEdit page button, scroll to the bottom of this page and you should see it there:

To avoid local setup, you can useGitHub 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.

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

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

1. Clone theaspire.dev repository.

   gitclonehttps://github.com/microsoft/aspire.dev.git

2. Navigate to theaspire.dev directory.

   cdaspire.dev

3. Install dependencies

   • pnpm
   • npm

   pnpminstall

4. Run the development server

   pnpmdev

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

5. View the site locally

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

We exposelint andformat scripts in thepackage.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.

<Steps>
1. First step with content
1. Second step with content
1. Third step with content
</Steps>

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 theaspire.dev repository to your own GitHub account

3. Create a new branch for your changes

   gitcheckout-bfeature/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 theCode of Conduct

When contributing toaspire.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.

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

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

---
title:My page title
---
Page content follows the second`---`.

Every page must include at least atitle. See thefrontmatter reference for all available fields and how to add custom fields.

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

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

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

Bold text is created with double asterisks:

**Bold text**

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

_Italic text_

Inline code is created with backticks:

`Inline code`

Links are created with square brackets and parentheses:

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

Renders as:

David Pine

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

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

Renders as:

Build your first Aspire app

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

-First item
-Second item
-Third item

Renders as:

• First item
• Second item
• Third item

Ordered lists use numbers:

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

Renders as:

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

Use triple backticks with a language identifier for syntax highlighting:

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

Renders as:

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

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

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

Renders as:

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

Use> to create blockquotes:

>This is a note or important callout.

Renders as:

This is a note or important callout.

Create tables using pipes| and hyphens-:

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

Renders as:

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

---

Renders as:

Use double tildes to create strikethrough text:

~~This text is crossed out~~

Renders as:

This text is crossed out

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

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

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]

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.

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

You can write mermaid diagrams as code blocks:

```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, “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 ofnote,tip,caution, ordanger in both Markdown andMDX:

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

// A code snippet, for example.

Additionally,aspire.dev supportsGitHub Alerts syntax with thecommunity plugin:

For example, you can write:

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

Renders as:

See the full demo here:Starlight: GitHub Alerts.

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.

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 inaspire.dev, simply import them at the top of your MDX file and use them like regular JSX components.

---
title:Example MDX Page
---
import{LinkButton}from'@astrojs/starlight/components';
Here's an example of an MDX page with a custom button:
<LinkButtonhref="https://aspire.dev"variant="primary">
Visit aspire.dev
</LinkButton>

Renders as:

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

TheAside component from Starlight can be used to create asides in your documentation:

---
title:Example MDX Page
---
import{Aside}from'@astrojs/starlight/components';
<Aside>Some content in an aside.</Aside>
<Asidetype="caution">Some cautionary content.</Aside>
<Asidetype="tip">
Other content is also supported in asides.
```js
// A code snippet, for example.
```
</Aside>
<Asidetype="danger">Do not give your password to anyone.</Aside>

Renders as:

// A code snippet, for example.

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

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

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

---
title:Example MDX Page
---
importLearnMorefrom'@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>

Renders as:

Here’s an example of using theLearnMore component:

• Issues - Report bugs or request features viaGitHub Issues
• Discussions - Join conversations inGitHub Discussions
• Discord - Connect with the community on theAspire Discord