# MDX

Dev Portal supports MDX files for creating rich content pages. MDX is a markdown format that allows you
to include JSX components in your markdown files.

## Getting Started

To use MDX in your documentation, simply create files with the `.mdx` extension instead of `.md`.
These files work exactly like regular markdown files but with all MDX features unlocked - you can
write normal markdown content and add JSX components whenever needed.

```
docs/
├── my-page.md      # Regular markdown
├── my-mdx-page.mdx # MDX with JSX support
```

## Custom Components

Dev Portal supports the use of custom components in your MDX files. This allows you to create reusable
components that can be used across multiple pages.

You can create a custom component in your project and reference it in the
[Dev Portal Configuration](./overview.md) file.

For example, create the `<MyCustomComponent />` component in a file called `MyCustomComponent.tsx`
in the `src` directory at the root of your project.

```tsx
export default function MyCustomComponent() {
  return <div>My Custom Component</div>;
}
```

In [Dev Portal Configuration](./overview.md) you will need to import the component and add it to the
`customComponents` option in the configuration.

```ts title=zudoku.config.ts
import MyCustomComponent from "./src/MyCustomComponent";

const config: ZudokuConfig = {
  // ...
  mdx: {
    components: {
      MyCustomComponent,
    },
  },
  // ...
};

export default config;
```

## JSX in Headings

JSX components in headings render in both the sidebar navigation and table of contents:

```mdx
# My Page <Badge>New</Badge>
```

Components must be registered via [`mdx.components`](#custom-components) to work in headings.