MDX

Squidoc keeps Markdown as the default docs format, while @squidoc/plugin-mdx adds .mdx discovery for projects that want a gradual path toward richer documents.

Install the plugin, then add it to docs.config.ts:

npx squidoc add plugin @squidoc/plugin-mdx

export default defineConfig({
  plugins: [
    "@squidoc/plugin-seo",
    "@squidoc/plugin-codeblocks",
    "@squidoc/plugin-article-tree",
    "@squidoc/plugin-mdx",
  ],
});

After that, Squidoc discovers files such as docs/api.mdx and routes them the same way it routes Markdown files. This page is written as an .mdx file and rendered by the dogfood site.

What works today

Use .mdx files for Markdown content, frontmatter, headings, links, lists, tables, and code blocks. The default Markdown renderer still handles the final HTML output, so the same plugins that enhance Markdown pages also run on .mdx pages.

---
title: API Guide
description: A guide written in an MDX file.
---

# API Guide

Regular Markdown content works here.

What does not work yet

Component-based MDX is not compiled yet. JSX imports and custom React-style components are currently treated as document text rather than interactive components.

import Callout from "../components/Callout";

<Callout>This is not supported yet.</Callout>

If you need reusable UI today, put it in a theme or plugin slot. Full MDX component compilation is a natural future plugin capability, but the current plugin is intentionally small: it adds .mdx discovery without changing the rest of the rendering pipeline.