MDX Docs

MDX Docs

Made with 🧘 by Quiet Mind Creative.

⚡ A lightweight React framework for building MDX documentation sites.

Welcome to the MDX Docs example site. This is the default demo site for the project. This site was built with MDX Docs.

MDX Docs turns MDX files into routed documentation pages with a built-in layout, sidebar, and navigation.

Check the Examples page to see some example pages that display React components alongside the documentation.

Features

  • MDX pages — write Markdown with embedded React components
  • Syntax highlighting with copy-to-clipboard on code blocks
  • Dark/light mode with system preference detection
  • Responsive sidebar navigation
  • Built on React 19, Material-UI 7, and Vite 6

Quick Start

Create a new documentation site:

bash
npx create-mdx-docs@latest my-docs
Create an MDX file in pages/: 
mdx
import { Button } from "@mui/material";


# Button


<Button variant="contained" color="primary">
  Primary Action
</Button>


```jsx
<Button variant="contained" color="primary">
  Primary Action
</Button>
```
Register your page in config/pages.js: 
js
const GettingStartedMDX = lazy(() => import("@pages/getting-started.mdx"));


export const pages = [
  // ...existing pages
  {
    name: "Getting Started",
    route: "/getting-started",
    component: GettingStartedMDX,
  },
];
Pages with isDefault: true do not appear in the sidebar navigation. Configure your site name and description in config/site.js. 
js
export const site = {
  name: "My Site",
  description: "My site description",
};

Writing MDX

MDX files are JSX, not HTML. A few things to keep in mind:

  • Inline styles must be objects, not strings — style={{ marginRight: '0.5rem' }} not style="margin-right: 0.5rem". A CSS string will cause a runtime error due to Emotion's JSX transform.
  • Use className instead of class.
  • Self-close void elements: <img />, <br />, <hr />.

Favicon

Place your favicon in the public/ directory and add a <link> tag to index.html: 
html
<head>
  <!-- ... -->
  <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
</head>
Vite serves files in public/ at the root path, so public/favicon.svg is accessible as /favicon.svg. Use .ico, .png, or .svg depending on your file.

Project Structure

none
my-docs/
├── pages/
│   └── home.mdx
├── config/
│   ├── pages.js
│   └── site.js
├── public/
│   └── favicon.svg
├── index.html
├── main.jsx
├── vite.config.js
└── package.json

Contributing

Contributions are welcome!

  1. Fork the repo
  2. Create a branch
  3. Submit a pull request
https://github.com/thequietmind/mdx-docs

Related Projects

License

MIT