MDX Documentation

MDX

MDX is an authorable format that lets you seamlessly write JSX in your Markdown documents. You can import components, such as interactive charts or alerts, and embed them within your content. This makes writing long-form content with components a blast 🚀.

more: mdxjs

Frontmatter

When creating MDX documentation files, you can include a set of key-value pairs that can be used to provide structured data. The format used is known as frontmatter

---
title: My Document
route: /tutorials/mdx-documentation/
type: tutorial
tags:
  - mdx
  - documentation
order: 0
---

Check all Document fields

Import React components

In MDX, you can import any React components and use them to create rich documentation pages:

---
title: My Button
---
import { Button } from 'theme-ui';

<Button onClick={() => alert('clicked')}>click me</Button>

Transclusion

mdxjs allows you to import external .mdx files statically and display their content:

---
title: Test Transclusion
---

import Transclusion from '../sections/transclusion.mdx';

<Transclusion />

By default, .md files are not transformed to react components - they are rather loaded with raw-loader and are translated as a string.

You can still display .md files using our <Markdown /> component:

---
title: Test Transclusion
---

import { Markdown } from '@component-controls/components';
import changelog from '../../../CHANGELOG.md';

<Markdown>{changelog}</Markdown>

If you prefer to compile .md files with mdxjs and use transclusion, you can set up a custom webpack config:

.config/buildtime.js

module.exports = {
  webpack: (config = {}) => {
    return {
      ...config,
      module: {
        ...config.module,
        rules: [
          ...config.module.rules.filter(rule => !rule.test.test('.md')),
          {
            test: /\.md$/i,
            use: [
              {
                loader: 'babel-loader',
                options: {
                  presets: ['@babel/preset-env', '@babel/preset-react'],
                },
              },
              '@mdx-js/loader',
            ],
          },
        ],
      },
    };
  },
};

And then use the imported markdown file as a react component:

---
title: Test Transclusion
---

import Changelog from '../../../CHANGELOG.md';

<Changelog />

Syntax highlighting

You can include source code in your MDX and MD documentation and add some useful parameters

Language

The language can be specified as the first parameter

```jsx
import { Button } from 'theme-ui';
```

Title

A title attribute can be added. Due to some current MDX limitations, the title can not contain spaces.

my-title

```jsx:title=my-title
import { Button } from 'theme-ui';
```

Highlight lines

You can specify a line to highlight

```jsx {2}
import { Button } from 'theme-ui';
<Button>click me </Button>;
```

Or a range of lines

```jsx {2-3}
import { Button } from 'theme-ui';
<Button>click me </Button>;
```

Emoji

You can use :emoji: in your documents

:rocket: :dog: :+1: = 🚀 🐶 👍

Getting started/External libraries

Writing Documentation/ESM Stories

Tutorial