{"schemaVersion":1,"title":"Write native MDX articles","url":"https://appgram.github.io/docsy/guides/tutorials/native-mdx","markdownUrl":"https://appgram.github.io/docsy/format-md/guides/tutorials/native-mdx","jsonUrl":"https://appgram.github.io/docsy/agent/pages/guides/tutorials/native-mdx.json","version":"current","locale":"en","markdown":"# Write native MDX articles\n\nMix Markdown with themed JSX components, keep Mintlify MDX sources, and explicitly opt into trusted custom components.\n\nWritten by: [nedimf](https://github.com/nedimf), [AppGram](https://appgram.dev)\n\nMDX 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.\n\n## Register an MDX article\n\nKeep the file outside `public/` and register it in `docsy.config.yaml`, exactly like a Markdown article:\n\n```yaml\ncontent:\n  mdx:\n    enabled: true\n    allowJavaScript: false\n    components: {}\n  articles:\n    - slug: getting-started\n      source: content/getting-started.mdx\n      title: Getting started\n      description: Install and configure your project.\n```\n\nYAML 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.\n\nSame content pipeline\n\nMDX participates in the heading rail, full-text search, Markdown/JSON exports, version and locale selection, and permission gates. Agent exports contain the rendered component text and code, not raw JSX or import statements.\n\n## Components that match your theme\n\nThese built-ins need no imports. They inherit the existing light/dark palette and local font stacks.\n\n[Bring your articles →](/docsy/guides/tutorials/migrate-mintlify)\n\nKeep supported Mintlify `.mdx` articles as MDX, with navigation, links and assets mapped into Docsy.\n\n[Keep plain Markdown →](/docsy/guides/tutorials/rich-articles)\n\nExisting articles and directive components continue to work. Mix both formats in one portal.\n\nNode\n\n```bash\nnpm install\nnpm run validate\nnpm run build\n```\n\nBun\n\n```bash\nbun install\nbun run validate\nbun run build\n```\n\n1. Write the article\n\n   Use Markdown headings, links, GFM tables and fenced examples together with JSX components.\n\n2. Register the source\n\n   Add the `.mdx` path under `content.articles` and choose its position in `navigation`.\n\n3. Validate and preview\n\n   Run the same validation and build commands as the rest of your documentation. Review the rendered result before deployment.\n\nAvailable built-ins\n\n| Component                                           | Purpose                                                                                  |\n| --------------------------------------------------- | ---------------------------------------------------------------------------------------- |\n| `Note`, `Info`, `Tip`, `Check`, `Warning`, `Danger` | Theme-aware callouts, with optional `title`                                              |\n| `Tabs`, `Tab`                                       | Keyboard-accessible tabs; use `title` on each tab and `group` or `sync` on the container |\n| `Steps`, `Step`                                     | Numbered steps with optional titles                                                      |\n| `Accordion`, `AccordionGroup`                       | Expandable sections; `defaultOpen` opens a section initially                             |\n| `CodeGroup`                                         | Tabbed fenced examples; fence metadata supplies the tab label                            |\n| `Card`, `CardGroup`                                 | Linked content cards; the group accepts one to three `cols`                              |\n| `Frame`                                             | A bordered figure wrapper                                                                |\n\nUse `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.\n\n## Declarative by default\n\nWith `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.\n\nThis is a restricted authoring mode, not a sandbox for arbitrary JavaScript. Imported source is parsed and checked without executing it.\n\n## Trusted JavaScript and custom components\n\nFor a repository whose executable content you trust, opt in explicitly:\n\n```yaml\ncontent:\n  mdx:\n    enabled: true\n    allowJavaScript: true\n    components:\n      ApiStatus: content/components/ApiStatus.tsx\n```\n\nThe registered module must export a default React component:\n\n```tsx\nexport default function ApiStatus({ children }) {\n  return <strong>{children}</strong>;\n}\n```\n\nUse `<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.\n\nExecutable content has your process permissions\n\nTrusted MDX runs during validation, builds and server-side rendering. Imports and expressions can access files, environment variables and the network. Never enable this for unchecked exports, reader submissions, or agent-generated code. Secrets are not protected from trusted MDX. The maintenance workflow remains restricted to Markdown and guarded YAML; it does not automatically edit `.mdx` files.\n\nMDX 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`.\n\nSet `content.mdx.enabled: false` to reject MDX entirely. [Migrate from Mintlify](/docsy/guides/tutorials/migrate-mintlify) to test your existing source without enabling JavaScript.\n\n","contentLocale":"en","isFallback":false,"authorship":{"authors":[{"name":"nedimf","kind":"human","github":"nedimf","avatar":"/docsy/assets/authors/nedimf.png","role":"AppGram","id":"nedimf","url":"https://github.com/nedimf"},{"name":"AppGram","kind":"organization","github":"AppGram","url":"https://appgram.dev","avatar":"/docsy/assets/ag-logo.svg","id":"appgram"}],"contributors":[],"reviewedBy":[]},"editUrl":"https://github.com/AppGram/docsy/edit/main/content/tutorials/native-mdx.mdx"}