Skip to main content

MDX

Check out the Mdx Aspect on Bit.dev

The MDX aspect integrates MDX with Bit to enable the authoring of component documentation and standalone content components, using the MDX format. The MDX format joins together the ease-of-use and readability of the Markdown syntax with the endless possibilities that are offered by JSX. The modularity that's offered by both technologies (MDX and Bit) enables MDX files to be exported to a remote scope and imported to other web projects, just like any other Bit component.

Example#

---displayName: Login formdescription: A simple login formlabels: ['react', 'ui', 'form']---
import { LoginForm } from './login-form'
## A live example
A simple example of live example:
```jsx live=true<LoginForm><LoginForm/>```
// An example of a documented component file-structure
├── login-form    ├── index.tsx    ├── login-form.compositions.tsx    ├── login-form.docs.md    ├── login-form.spec.tsx    └── login-form.tsx

Features#

  • Powerful component composition: Author clear and engaging documentation that integrates readable Markdown syntax, Bit's live playground and your own customized components.
  • Docs that look and feel like Bit: Component docs written with MDX (like the one you're reading right now) are themed using Bit's [Documenter design system to provide a look-and-feel that is consistent with the Workspace/Scope UI.
  • Bit component frontmatter: Use Bit's YAML frontmatter to add or override metadata to the component being documented.
  • A simple-to-use live playground: Use MDX's user-friendly syntax to add live examples of code. No need to worry about dependencies - any module used by the doc file will also be available to code running in the live playground.
  • Independent MDX components: Author consumable independent content components that can be shared across web projects. Use it to maintain a consistent "voice & tone" and to keep your content always up-to-date.

Quick start#

The MDX aspect is used by various Bit environments. To use it, set your workspace configuration to use an MDX supported environment.

As a default, MDX will only be used for component documentation. To enable the compilation of MDX components, set the mdx property to true.

{  "teambit.workspace/variants": {    "*": {      "teambit.react/react": {        "mdx": true      }    }  }}

Usage#

Using the frontmatter API#

Bit parses your code to generate metadata for your components. This metadata is presented in the component's documentation and is used by Bit.dev's search engine. To override it, use Bit's frontmatter properties, at the top of your MDX file.

---displayName: Login Formdescription: My customized descriptionlabels: ['react', 'typescript', 'ui', 'form']---
  • displayName string overrides the component name.
  • description string overrides the component description/abstract.
  • labels string[] overrides the component labels/tags.

Using the live playground#

To use Bit's live playground add live=true to your codeblock.

```jsx live=true    () => {        return <p> Hello World! </p>    }```;

The above MDX snippet will be rendered like so:

() => {  return <p> Hello World! </p>;};

Using the live playground with external modules#

The live playground can access the docs file dependencies. To use an external module, first import it to the docs file.

For example:

---description: A frontmatter exammple.---
import _ from 'lodash';
```jsx live=true    () => {        return <p> { _.camelCase('Hello world') } </p>    }```

The above MDX snippet will be rendered like so:

() => {  return <p> {_.camelCase('Hello world')} </p>;};

Use-cases and best practices#

Documenting components#

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 offered by integrating code into it. In addition to that, the modularity that's offered by both technologies (MDX and Bit) enables importing and integrating segments of content from the documentation of other components, into a single documentation file. This can be done to document your components in a way that reflects the way they are built - through a composition of components. That will help in keeping your docs always up-to-date as changes made to a sub-component will propagate to the component's docs.

Linking to external pages is, in many cases, the result of technological limitations and not the preferred solution. If most people reading your docs need to visit an external page in order for them to get the full explanation, then it makes more sense to have that external text integrated into your docs (by importing it).


Now that we have MDX and Bit, that can be done quite easily.

To start writing your docs with MDX, add a *.docs.mdx or *.docs.md file to the component's directory and Bit will render it in the component's 'Overview' tab, in the Workspace UI (and later on, after it is exported, in the Scope UI). Bit's development server will hot-reload your documentation to reflect any changes made to it, in real time.

// An example documented component file-structure
├── login-form    ├── index.tsx    ├── login-form.compositions.tsx    ├── login-form.docs.mdx    ├── login-form.spec.tsx    └── login-form.tsx

Make sure the Bit environment used by your component supports MDX!

Independent MDX components#

Building with components, whether they are code or markdown, means easier maintainability and better reusability. That naturally translates into faster delivery and more consistent content across web projects.

The MDX aspect can be used to author independent MDX components. Components can be written using MDX and compiled to plain JS, to be consumed by other web projects. Since the MDX aspect is used and handled by your environment, this feature is turned on using the environment's configurations.

For example, to turn on this feature in @teambit.react/react environment:

{  "teambit.workspace/variants": {    "*": {      "teambit.react/react": {        "mdx": true      }    }  }}

Collaborating with non-developers#

Your docs are not only for other developers. A component's documentation can be used as a hub for collaboration between different stakeholders.

The verbal descriptions, live examples, images and links to other related artifacts, are all communicating the component's story with little or no code.


The below example shows easily detectable discrepancies between design and implementation, seen in a demo documentation for a "button" component.

// Buttons do not follow the design when 'disabled'<>  <Button disabled importance="cta" style={{ width: 120 }}>    Primary  </Button>
  <Button importance="ghost" style={{ width: 120 }}>    Secondary  </Button>
  <Button style={{ width: 120 }}>Normal</Button></>