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.

📋 Prerequisites

Before you begin, ensure you have the following installed:

• Node.js (LTS version recommended) - For running the development server
• 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

   npm install

4. Run the development server

   npm run dev

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

5. View the site locally

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

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

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

Nota

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

Dica

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
1. Second step
1. Third step

Renders as:

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

Nota

Use 1. for all items in an ordered list—Markdown will automatically number them correctly.

Code blocks

Use triple backticks with a language identifier for syntax highlighting:

src/content/docs/example.md

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

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

Dica

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:

src/content/docs/example.md

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

:::caution
Some cautionary content.
:::

:::caution

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.

Caution

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.

For the Starlight component, 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

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

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:

Nota

Some content in an aside.

Cuidado

Some cautionary content.

Dica

Other content is also supported in asides.

// A code snippet, for example.

Perigo

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

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