MDX is a first-class article source, alongside Markdown. This page is itself rendered from content/tutorials/native-mdx.mdx: the cards, tabs, steps, callouts and code below are live MDX, not screenshots or converted JSON.

Register an MDX article

Keep the file outside public/ and register it in docsy.config.yaml, exactly like a Markdown article:

Code example
content:
  mdx:
    enabled: true
    allowJavaScript: false
    components: {}
  articles:
    - slug: getting-started
      source: content/getting-started.mdx
      title: Getting started
      description: Install and configure your project.

YAML owns the title, route, version and locale. Optional YAML frontmatter is accepted in .mdx sources but does not override registration metadata. .md files continue to use Docsy's Markdown directives; .mdx files use JSX components.

Components that match your theme

These built-ins need no imports. They inherit the existing light/dark palette and local font stacks.

Bring your articles

Keep supported Mintlify .mdx articles as MDX, with navigation, links and assets mapped into Docsy.

Keep plain Markdown

Existing articles and directive components continue to work. Mix both formats in one portal.

Node

Node
npm install
npm run validate
npm run build

Bun

Bun
bun install
bun run validate
bun run build

  1. Write the article

    Use Markdown headings, links, GFM tables and fenced examples together with JSX components.

  2. Register the source

    Add the .mdx path under content.articles and choose its position in navigation.

  3. Validate and preview

    Run the same validation and build commands as the rest of your documentation. Review the rendered result before deployment.

Available built-ins
ComponentPurpose
Note, Info, Tip, Check, Warning, DangerTheme-aware callouts, with optional title
Tabs, TabKeyboard-accessible tabs; use title on each tab and group or sync on the container
Steps, StepNumbered steps with optional titles
Accordion, AccordionGroupExpandable sections; defaultOpen opens a section initially
CodeGroupTabbed fenced examples; fence metadata supplies the tab label
Card, CardGroupLinked content cards; the group accepts one to three cols
FrameA bordered figure wrapper

Use content.components to enable the corresponding groups: note, tip, warning, danger, tabs, steps, accordion, code-group, card, and frame. All are enabled by default. Mintlify's icon names, platform integrations and all layout-specific props are not reproduced; supported components use Docsy's UI.

Declarative by default

With allowJavaScript: false, Docsy accepts built-in components, a bounded set of ordinary HTML tags, quoted attributes, and literal values such as cols={2}. It rejects imports/exports, function calls, variable expressions, attribute spreads, event handlers and executable HTML. Unknown components fail instead of dropping their content. JSX must be valid MDX: close tags, and use JSX comments ({/* comment */}), not HTML comments.

This is a restricted authoring mode, not a sandbox for arbitrary JavaScript. Imported source is parsed and checked without executing it.

Trusted JavaScript and custom components

For a repository whose executable content you trust, opt in explicitly:

Code example
content:
  mdx:
    enabled: true
    allowJavaScript: true
    components:
      ApiStatus: content/components/ApiStatus.tsx

The registered module must export a default React component:

ApiStatus.tsx
export default function ApiStatus({ children }) {
  return <strong>{children}</strong>;
}

Use <ApiStatus>Available</ApiStatus> in MDX, or use standard local ESM imports directly in the article. Local .js, .jsx, .ts, .tsx and .mdx modules are bundled on the server. Keep component files under content/ so the standard Docker images include them.

MDX is rendered to HTML on the server or at build time. React components do not receive automatic browser hydration: hooks requiring a browser, React event handlers and arbitrary interactive widgets are not supported by this renderer. Docsy's built-in tabs, code-copy controls and accordions use its existing client behavior. Root-relative article links and assets respect site.basePath.

Set content.mdx.enabled: false to reject MDX entirely. Migrate from Mintlify to test your existing source without enabling JavaScript.