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.

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.

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

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.

1. First step with content

1. Second step with content

1. Third step with content

➡️ Git workflow

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

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

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

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

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

Text formatting

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

Links are created with square brackets and parentheses:

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

Renders as:

David Pine

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

[Build your first Aspire app](/docs/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

Code blocks

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");

Blockquotes

Use > to create blockquotes:

> This is a note or important callout.

Renders as:

This is a note or important callout.

Tables

Create tables using pipes | and hyphens -:

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

Renders as:

Horizontal rules

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

---

Renders as:

Strikethrough

Use double tildes to create strikethrough text:

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

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

> [!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 supports GitHub Alerts syntax with the community plugin:

For example, you can write:

Note

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

Renders as:

See the full demo here: Starlight: GitHub Alerts.

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

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

---
title: Example MDX Page
---
  
  
Here's an example of an MDX page with a custom button:
  
Visit aspire.dev

Renders as:

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

Visit aspire.dev

Aside component

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

---
title: Example MDX Page
---
  
  
<Aside>Some content in an aside.</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.

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:

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:

---
title: Example MDX Page
---
  
  
Here's an example of using the `LearnMore` component:

Renders as:

Here's an example of using the LearnMore component:

🆘 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