MDX

The MDX format is perfect for writing documentation for components, as it joins together the ease-of-use and readability of the Markdown syntax with the great flexibility that's enabled by JSX.

MDX docs use a Bit-specific flavor of MDX that extends the docs front matter and renders them using Bit's MDX layout.

Documenting components with MDX

MDX is supported by Envs that use Bit's MDX Webpack loader for their component previews. These include the React Env, Node Env, and many others.

To use MDX for component documentation, create a docs file with the mdx or md extensions.

For example:

.
├── card.composition.tsx
├── card.docs.mdx
├── card.module.scss
├── card.spec.tsx
├── card.tsx
└── index.ts
CopiedCopy

Building MDX components

MDX can be used to create independent content components. That is, content that is not an internal dependency of a component, but a component in and of itself (that can be used by other components as an external dependency). This is done by setting the MDX component to use the MDX Env.

Create an MDX component

As any other component, MDX components can be created manually or using a pre-configured template.

In the below example, we'll use MDX' component template:

bit create mdx content/my-mdx-component
CopiedCopy

This will generate the following files:

.
├── index.ts
├── my-mdx-component.composition.tsx
├── my-mdx-component.docs.mdx
└── my-mdx-component.mdx
CopiedCopy

Please note that the entry file (index) should export the MDX content as default. For example:

export { default as MyMdxComponent } from './my-mdx-component.mdx';
CopiedCopy

Set components to use the MDX Env

Use Variants to set the MDX components to use the MDX Env. In the example below, we will use the content namespace to select all our content components:

"teambit.workspace/variants": {
    "{content/**}": {
      "teambit.mdx/mdx": {}
    },
  }
CopiedCopy

MDX docs structure and features

Metadata

Use Bit's description and labels front matter properties to customize the docs 'abstract' and 'labels'.

The front matter must be the first thing in the file and must take the form of valid YAML set between triple-dashed lines.

For example:

---
description: 'Renders a heading with customizable element prop'
labels: ['h1', 'h2', 'h3', 'h4', 'h5', 'h6']
---
CopiedCopy

Content

The MDX file content is compiled by Bit and exported as the default. There's no need to wrap the content section in a class or a function.

For example:

## Heading

A heading component that renders a different heading element depending on what you pass into it. It also renders a text for the Heading.
CopiedCopy

Live examples

Add static codeblocks to your docs using the standard markdown syntax:

For example:

import { Heading } from './heading';

```jsx
<Heading element="h2">heading</Heading>
```
CopiedCopy

Use Bit's live playground component by adding the live attribute to your codeblock.

For example:

import { Heading } from './heading';

```jsx live
<Heading element="h2">
  heading<div>more heading</div>
</Heading>
```
CopiedCopy