Forge Markdown MDX Syntax (.mdx)

A guide to every Markdown and MDX feature you can use in .mdx files across Uvilo OS docs. Our site runs on Astro Starlight, which extends standard Markdown with JSX components and Expressive Code enhancements.

For .md-only syntax (directive-style asides), see Forge Markdown Syntax.

Standard Markdown

Everything you already know works:

• Bold with **double asterisks**
• Italic with *single asterisks*
• Strikethrough with ~~double tildes~~
• Headings with #, ##, ###, up to ######
• Unordered lists with - or *
• Ordered lists with 1., 2., 3.
• Links with [text](url)
• Images with ![alt](url)
• Horizontal rules with ---
• Inline code with single backticks
• Blockquotes with >

Example:

Bold text, italic text, and strikethrough are all supported.

A heading

• An unordered item
• Another item

1. First ordered item
2. Second ordered item

Visit Uvilo

A blockquote with something important to say.

---

Asides

Asides are colored callout boxes for secondary information. In .mdx files, use the component syntax.

There are four types:

Type	Color	Icon	Use for
note	Blue	ℹ️	Informational notes
tip	Purple	🚀	Helpful suggestions
caution	Yellow	⚠️	Warnings to be careful
danger	Red	🛑	Critical warnings

Basic asides

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

<Aside type="note">
This is a note aside.
</Aside>

<Aside type="tip">
Here's a helpful tip!
</Aside>

<Aside type="caution">
Be careful with this approach.
</Aside>

<Aside type="danger">
Do not delete the production database!
</Aside>

Result:

Note

This is a note aside.

Tip

Here’s a helpful tip!

Caution

Be careful with this approach.

Danger

Do not delete the production database!

Custom titles

<Aside type="caution" title="Watch out!">
This has a custom title.
</Aside>

Result:

Watch out!

This has a custom title.

Asides can contain nested Markdown, including code blocks.

Tabs

Show content in switchable tabs.

Basic tabs

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

<Tabs>
  <TabItem label="npm">
    ```bash
    npm install my-package
    ```
  </TabItem>
  <TabItem label="pnpm">
    ```bash
    pnpm add my-package
    ```
  </TabItem>
  <TabItem label="yarn">
    ```bash
    yarn add my-package
    ```
  </TabItem>
</Tabs>

Result:

npm

npm install my-package

pnpm

pnpm add my-package

yarn

yarn add my-package

Synced tabs

Tabs with the same syncKey stay in sync across the page:

<Tabs syncKey="package-manager">
  <TabItem label="npm">Run `npm install`</TabItem>
  <TabItem label="pnpm">Run `pnpm install`</TabItem>
</Tabs>

Result:

npm

Run npm install

pnpm

Run pnpm install

Tabs with icons

<Tabs>
  <TabItem label="Stars" icon="star">Sirius, Vega, Betelgeuse</TabItem>
  <TabItem label="Planets" icon="sun">Mercury, Venus, Earth</TabItem>
  <TabItem label="Moons" icon="moon">Io, Europa, Ganymede</TabItem>
</Tabs>

Result:

Stars

Sirius, Vega, Betelgeuse

Planets

Mercury, Venus, Earth

Moons

Io, Europa, Ganymede

Steps

Create numbered step-by-step guides.

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

<Steps>

1. **Install the package**

   ```bash
   npm install my-package
   ```

2. **Configure your project**

   Create a config file in your project root.

3. **Import and use**

   ```js
   import { myFunction } from 'my-package';
   myFunction();
   ```

</Steps>

Result:

1. Install the package

   npm install my-package

2. Configure your project

   Create a config file in your project root.

3. Import and use

   import { myFunction } from 'my-package';
   myFunction();

FileTree

Display directory structures visually.

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

<FileTree>

- astro.config.mjs
- package.json
- src
  - components
    - Header.astro
    - Title.astro
  - pages/

</FileTree>

Result:

• astro.config.mjs
• package.json
• Directorysrc

  • Directorycomponents

    • Header.astro
    • Title.astro
  • Directorypages/

    • …

Cards

Card

Display information in styled boxes.

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

<Card title="Getting Started" icon="rocket">
  Learn how to set up your first project in minutes.
</Card>

Result:

Getting Started

Learn how to set up your first project in minutes.

CardGrid

Arrange multiple cards in a responsive grid. Add the stagger prop for a subtle animation.

import { Card, CardGrid } from '@astrojs/starlight/components';

<CardGrid>
  <Card title="Installation" icon="laptop">
    Step-by-step installation instructions.
  </Card>
  <Card title="Configuration" icon="setting">
    Customize your setup.
  </Card>
  <Card title="Integrations" icon="puzzle">
    Connect with your favorite tools.
  </Card>
  <Card title="Deployment" icon="rocket">
    Deploy to production with ease.
  </Card>
</CardGrid>

Result:

Installation

Step-by-step installation instructions.

Configuration

Customize your setup.

Integrations

Connect with your favorite tools.

Deployment

Deploy to production with ease.

LinkCard and LinkButton

Navigation and call-to-action components.

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

<LinkCard
  title="Getting Started Guide"
  description="Learn the basics of setting up your project."
  href="/guides/getting-started/"
/>

<LinkButton href="/getting-started/">Get Started</LinkButton>
<LinkButton href="/guides/" variant="secondary">Read the Guides</LinkButton>

Result:

Getting Started Guide Learn the basics of setting up your project.

Get Started Read the Guides

Icon

Insert icons from Starlight’s built-in icon set.

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

<Icon name="star" />
<Icon name="rocket" size="1.5rem" />
<Icon name="heart" color="red" />

Result:

Common icons: star, rocket, github, sun, moon, pencil, external, document, setting, information, warning, check, heart, download.

Code Blocks

Syntax highlighting

Add a language identifier after the opening backticks:

```js
const greeting = "Hello, world!";
console.log(greeting);
```

Result:

const greeting = "Hello, world!";
console.log(greeting);

Line highlighting

Highlight specific lines with curly braces after the language. Use {1,4-6} for non-consecutive lines.

```js {2-3}
function demo() {
  // This line and the next are highlighted
  return 'highlighted';
}
```

Result:

function demo() {
  // This line and the next are highlighted
  return 'highlighted';
}

Mark inserted and deleted text

Show additions and removals with ins= and del=. Default markers (in quotes) highlight in neutral yellow, ins= in green (additions), del= in red (deletions).

```js "return true;" ins="inserted" del="deleted"
function demo() {
  console.log('These are inserted and deleted marker types');
  // The return statement uses the default marker type
  return true;
}
```

Result:

function demo() {
  console.log('These are inserted and deleted marker types');
  // The return statement uses the default marker type
  return true;
}

Window frames and titles

Expressive Code adds a terminal/editor window frame around code blocks by default. Use title= to add a filename.

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
export default defineConfig({});
```

Result:

astro.config.mjs

import { defineConfig } from 'astro/config';
export default defineConfig({});

Mermaid Diagrams

Our site supports Mermaid diagrams inline:

```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E
```

Result:

graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E

Mermaid supports flowcharts, sequence diagrams, class diagrams, state diagrams, Gantt charts, and more.

Frontmatter

Frontmatter contains metadata used to identify the document and organize it in the sidebar. This is handled automatically by Forge agents, and never edited by humans.

Full frontmatter reference

---
title: My Documentation Page
description: Learn how to use the example feature.

# Table of contents
tableOfContents:
  minHeadingLevel: 2
  maxHeadingLevel: 4
# tableOfContents: false  # hide TOC entirely

# Page template ('doc' is default, 'splash' for landing pages)
template: doc

# Last updated date
lastUpdated: 2024-01-15

# Pagination
prev:
  link: /guides/introduction
  label: Introduction
next: false  # hide next link

# Sidebar customization
sidebar:
  label: Custom Label
  order: 1
  hidden: false
  badge:
    text: New
    variant: tip

# Announcement banner
banner:
  content: We just launched v2.0!

# Exclude from search
pagefind: false

# Draft (hidden in production)
draft: false
---

Summary

Feature	Syntax
Code highlighting	```js {2-3}
Insert/delete markers	ins="text" del="text"
Code block titles	title="file.js"
Asides	<Aside type="note">
Tabs	<Tabs> / <TabItem>
Steps	<Steps>
FileTree	<FileTree>
Cards	<Card> / <CardGrid>
LinkCard / LinkButton	<LinkCard> / <LinkButton>
Icons	<Icon name="star">
Mermaid	```mermaid
Frontmatter	---yaml---

For the full Starlight component API, see the Starlight Components Reference. For Expressive Code options, see the Expressive Code docs.