MDX & Starlight Cheatsheet

This page acts as a reference for writing documentation. It covers standard Markdown, MDX features, and Starlight specific components.

1. Admonitions (Callouts)

Use these to highlight critical information. You do not need to import anything to use these.

Styles

Syntax:

:::note
**General Info:** Useful context or non-critical information.
:::

:::tip
**Pro Tip:** Helpful advice or shortcuts.
:::

:::caution
**Warning:** Be careful when doing this.
:::

:::danger
**Critical:** This action can break things or cause data loss.
:::

Result:

Custom Titles

You can override the default title of any admonition.

Syntax:

:::tip[Did you know?]
You can customize the title of these boxes!
:::

Result:

2. Code Blocks

Starlight uses Expressive Code by default.

Basics & Titles

Syntax:

```php title="app/Models/User.php"
<?php

namespace App\Models;

class User extends Authenticatable
{
    // ...
}
```

Result:

<?php

namespace App\Models;

class User extends Authenticatable
{
    // ...
}

Highlighting Lines

Use {RANGE} to highlight specific lines.

Syntax:

```js {2-3}
export default defineConfig({
  title: 'My Docs',
  social: {
    github: 'https://github.com',
  },
});
```

Result:

export default defineConfig({
  title: 'My Docs',
  social: {
    github: 'https://github.com',
  },
});

Diff Views (Add/Remove)

Use + or - at the start of a line to show changes (great for tutorials).

Syntax:

```js
  function add(a, b) {
-   return a - b;
+   return a + b;
  }
```

Result:

  function add(a, b) {
-   return a - b;
+   return a + b;
  }

3. Tabs

Useful for showing instructions for different operating systems or package managers.

Syntax:

<Tabs>
  <TabItem label="NPM" icon="seti:npm">
    {/* ```bash
    npm install astro
    ``` */}
  </TabItem>
  <TabItem label="Composer" icon="seti:php">
    {/* ```bash
    composer require laravel/framework
    ``` */}
  </TabItem>
</Tabs>
// Code commented to prevent MDX from breaking

Result:

NPM
Composer

npm install astro

composer require laravel/framework

4. Steps & Processes

Use the <Steps> component to create numbered guides.

Syntax:

<Steps>

1. **Clone the Repo**
   Run `git clone ...`

2. **Install Dependencies**
   Run `composer install`

3. **Profit**
   Deploy to production.

</Steps>

Result:

Clone the Repo Run git clone ...
Install Dependencies Run composer install
Profit Deploy to production.

5. File Trees

Excellent for showing project structure or where a file is located.

Syntax:

<FileTree>
- app/
  - Models/
    - User.php
  - Http/
    - Controllers/
      - ProjectController.php
- database/
- .env
</FileTree>

Result:

Directoryapp/
- DirectoryModels/
  - User.php
- DirectoryHttp/
  - DirectoryControllers/
    ProjectController.php
Directorydatabase/
- …
.env

6. Cards & Grids

Use these for landing pages or grouping links.

Syntax:

<CardGrid>
  <Card title="Laravel" icon="rocket">
    Standard PHP Framework.
  </Card>
  <Card title="React" icon="seti:react">
    Frontend Library.
  </Card>
</CardGrid>

Result:

Laravel

Standard PHP Framework.

React

Frontend Library.

7. Link Cards

Prominent links to other parts of the documentation.

Syntax:

<LinkCard
  title="Deployment Guide"
  description="Learn how to deploy to Forge."
  href="/playbooks/deployment/laravel-forge"
/>

Result:

Deployment Guide Learn how to deploy to Forge.

8. Badges

Small status indicators.

Syntax:

<Badge text="New" variant="tip" size="small" />
<Badge text="Deprecated" variant="caution" size="medium" />
<Badge text="Draft" variant="note" size="large" />

Result:

New Deprecated Draft

9. Standard Markdown

Just a reminder of the basics.

Feature	Syntax	Result
Bold	`Bold`	Bold
Italic	`Italic`	Italic
Link	`[Google](https://google.com)`	Google
Inline Code	`code`	`code`

Tables

Syntax:

| Syntax | Description |
| :--- | :----------- |
| Header | Title |
| Paragraph | Text |

Result:

Syntax	Description
Header	Title
Paragraph	Text