MDX Components

mdsvr supports MDX — Markdown with JSX. This allows you to use interactive components directly in your documentation.

ℹ️ Info

MDX must be enabled in _mdsvr/settings.json with "mdx.enabled": true.

Callout

Use callouts to highlight important information:

<Callout type="info">This is an informational callout.</Callout>

<Callout type="warning" title="Important">
  This will delete all your data.
</Callout>

Types

ℹ️ Info
Info — General information and tips
⚠️ Warning
Warning — Caution about potential issues
🚫 Danger

Danger — Critical warnings about destructive actions

✅ Success

Success — Positive confirmation or success states

💡 Tip
Tip — Helpful suggestions and best practices

Steps

Create step-by-step guides:

<Steps>
  ### Step 1: Install
  Run `npm install mdsvr`

### Step 2: Configure

Create your `_mdsvr/settings.json`

### Step 3: Launch

Run `npx mdsvr ./docs`

</Steps>

Install the package

Run npm install mdsvr

Create your docs folder

Create a ./docs directory with some .md files

Start the server

Run npx mdsvr ./docs --open

Cards

Display links as beautiful cards:

<Card title="Quick Start" icon="⚡" href="#">
  Get up and running in 5 minutes
</Card>
⚙️Configuration

Full settings reference

Card Groups

📝Markdown

Standard Markdown support

⚛️MDX

React components in docs

🎨Themes

Dark and light mode

🔍Search

Full-text search

Tabs

Organize content in tabs:

<Tabs items={["npm", "yarn", "pnpm"]}>
  <Tab>```bash npm install mdsvr ```</Tab>
  <Tab>```bash yarn add mdsvr ```</Tab>
  <Tab>```bash pnpm add mdsvr ```</Tab>
</Tabs>

Code Groups

Group related code blocks:

<CodeGroup title="Installation">
  ```bash npm npm install mdsvr ``` ```bash yarn yarn add mdsvr ``` ```bash pnpm
  pnpm add mdsvr ```
</CodeGroup>
Configuration
{
  "site": {
    "title": "My Docs"
  }
}

module.exports = {
  site: {
    title: "My Docs",
  },
};

Accordion

Create collapsible sections:

<Accordion title="Is this free?">
  Yes, mdsvr is open source under MIT license.
</Accordion>

Badge

Add status badges inline:

New feature <Badge color="green">New</Badge>

Beta feature <Badge color="orange">Beta</Badge>

Deprecated <Badge color="red">Deprecated</Badge>

Available colors: green, orange, red, blue, purple, gray

  • New — New features
  • Beta — Beta features
  • Deprecated — Deprecated features
  • Info — Informational
  • Tip — Tips and tricks
  • Note — General notes

Mermaid

Create diagrams with Mermaid syntax:

<Mermaid>
  graph TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Great!]
    B -->|No| D[Debug]
    D --> E[Fix Issues]
    E --> B
</Mermaid>
💡 Tip

Mermaid diagrams are rendered client-side, so they work without any server-side dependencies.

Frontmatter

All MDX files support YAML frontmatter for metadata:

---
title: Page Title
description: Page description for SEO
image: ./assets/og-image.png
date: 2025-01-15
author: John Doe
tags: [setup, quickstart]
noIndex: false
---

# Your Content

This metadata is used for:

  • SEO <title> and meta tags
  • Open Graph / Twitter Cards
  • RSS feed entries (when date is present)
  • Search index weighting

MDX Plugins

You can add custom remark and rehype plugins to extend MDX functionality:

{
  "mdx": {
    "enabled": true,
    "remarkPlugins": ["remark-gfm"],
    "rehypePlugins": ["rehype-slug"]
  }
}

Options:

  • remarkPlugins: Array of remark plugin names for markdown transformations
  • rehypePlugins: Array of rehype plugin names for HTML transformations

Currently, mdsvr includes these built-in plugins by default:

  • remark-frontmatter - Parse YAML frontmatter
  • remark-gfm - GitHub Flavored Markdown support
  • remark-mdx-frontmatter - MDX frontmatter support
  • rehype-slug - Generate heading IDs for anchors
  • rehype-autolink-headings - Auto-link headings

You can add additional plugins by installing them and adding their names to the arrays.