Skip to content
Kubernetes Template

Why MDX?

MDX extends Markdown with JSX component support. Starlight provides a rich set of built-in components that make documentation interactive without writing custom code.

Built-in components

Section titled “Built-in components”

Starlight ships components for tabs, cards, asides, badges, and more. Import them from @astrojs/starlight/components and use them directly in your content.

Here is a tabbed install guide:

bash npm install my-package

Component syntax

Section titled “Component syntax”

MDX uses JSX syntax inside Markdown. Components are imported at the top and used as tags throughout the content:

---
title: Install Guide
---


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


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

Live example with cards:

Fast

Built for speed.

Safe

Secure by default.

Highlights:

  • Standard Markdown links [text](url) work everywhere — no need to drop into HTML <a> tags.
  • Bold, italic, and other inline formatting work naturally inside components.
  • Editor tooling (syntax highlighting, autocomplete, error checking) works out of the box with .mdx files.

Editor tooling

Section titled “Editor tooling”

This is MDX’s strongest practical advantage for developer-authored docs:

  • VS Code and other editors recognize .mdx files natively with syntax highlighting
  • TypeScript integration catches component import errors before build time
  • Autocomplete for component props works through standard JSX tooling
  • Go to definition jumps from component usage to its source

Type safety

Section titled “Type safety”

MDX files can leverage TypeScript-aware tooling. A typo like <Aside type="warningg"> gets flagged by your editor before you even build. Component props are typed, so you get autocomplete for valid values.

Flexibility

Section titled “Flexibility”

MDX supports importing any Astro, React, Solid, or Vue component. This means custom interactive widgets — charts, demos, embedded tools — work with a simple import:

import MyChart from "../../components/MyChart.astro";


<MyChart data={[1, 2, 3]} />

The component handles hydration and rendering. The content author just imports and uses it.

Summary comparison

Section titled “Summary comparison”

Imports

Components are imported explicitly at the top of each file. Clear dependencies, no magic.

Syntax

JSX mixed with Markdown. Familiar to anyone who writes React, Solid, or Vue.

Editor Support

Full syntax highlighting, autocomplete, go-to-definition, and error checking in VS Code and other editors.

Type Safety

TypeScript-aware tooling catches prop errors and missing imports before build time.