![\"admirable.mdx-press\"](\"https://i.imgur.com/SlZD85b.png\")
\n\n \n
![\"admirable](\"docs/badge-admirable.svg\"){kind=icon}
\n ![\"licence](\"docs/badge-licence.svg\"){kind=icon}
\n ![\"admirable](\"docs/badge-public.svg\"){kind=icon}
\n\nA native Rspack/Rsbuild plugin that compiles `.mdx` files directly into Vue components, with blazing-fast native performance and built-in dev-server HMR — edit a `.mdx` file and see your changes update instantly, just like any other component in your project.\n\nBuilt for and used by [`admirable-oss/kyc`](https://github.com/admirable-oss/kyc)'s design-system app (`apps/identity`), and published as its own package because the problem it solves — content-authored-separately-from-code that still hot-reloads — isn't specific to that app.\n\n## Why this exists\n\nThe obvious tool for \"MDX in a bundler\" is [`unplugin-vue-markdown`](https://github.com/unplugin/unplugin-vue-markdown) or `@mdx-js/loader`. Both were tried here first and didn't work with Rsbuild's Vue toolchain (`rspack-vue-loader`, a different implementation than webpack's `vue-loader`) — a separately-registered rspack plugin injecting its own module rule has no ordering guarantee against `@rsbuild/plugin-vue`'s own rule for the same file, so the markdown transform silently never ran.\n\nmdx-press takes a narrower, more direct approach: one loader, chained into the **same** module rule as `rspack-vue-loader`, with a documented, deterministic execution order. No unplugin abstraction layer, no separate plugin registration to race against.\n\n## What you get\n\n- `.mdx` files compile to real Vue components — no `v-html`, no runtime markdown parsing in the browser.\n- Each compiled component has two static named exports: `headings` (an `{ id, level, text }[]` outline of its `h2`/`h3`s) and `frontmatter` (its `---` YAML block, flat string fields only).\n- Real HMR, inherited from `rspack-vue-loader` itself — not a custom dev-server hack.\n- One runtime dependency tree: `markdown-it` + `markdown-it-anchor`. No MDX/JSX compiler, no Babel.\n\n## Install\n\n```bash\npnpm add @admirable-oss/mdx-press\n```\n\nRequires `@rsbuild/plugin-vue` to already be configured in your project — mdx-press relies on the `VueLoaderPlugin` it registers and doesn't register a second one.\n\n## Setup\n\n```ts\n// rsbuild.config.ts\nimport { pluginMdxPress } from \"@admirable-oss/mdx-press\";\nimport { defineConfig } from \"@rsbuild/core\";\nimport { pluginVue } from \"@rsbuild/plugin-vue\";\n\nexport default defineConfig({\n plugins: [\n pluginVue(),\n pluginMdxPress({\n // Optional: Tailwind (or any) utility classes injected onto generated\n // tags — there's no Vue template to put class= on markdown-generated\n // HTML, so this is how you theme it.\n classes: {\n h2: \"text-2xl font-bold\",\n h3: \"text-lg font-semibold\",\n paragraph: \"leading-relaxed\",\n list: \"list-disc pl-5\",\n inlineCode: \"rounded bg-gray-100 px-1.5 py-0.5 font-mono\",\n },\n }),\n ],\n});\n```\n\nAdd the ambient module declaration so TypeScript knows what importing a `.mdx` file gives you:\n\n```json\n// tsconfig.json\n{\n \"compilerOptions\": {\n \"types\": [\"@admirable-oss/mdx-press/client\"]\n }\n}\n```\n\n## Usage\n\nWrite content in `.mdx` — plain markdown, plus raw HTML for anything that needs a visual treatment markdown can't express (styled with the same utility classes as the rest of your app, since it's just HTML):\n\n```mdx\n---\ntitle: Colors\n---\n\n## Foundation\n\n### Colors\n\n