Fumadocs Transpiler

1.3.0 verified Fri May 01 auth: no javascript

A Node.js CLI and library (v1.3.0) that converts annotated Markdown files into Fumadocs-compatible React/MDX components. Uses triple-colon (`:::`) annotation syntax for built-in components like callouts, tabs, steps, accordions, code blocks, files, and banners. Supports bidirectional conversion (Markdown ↔ MDX), watch mode, dry run, title/frontmatter auto-extraction, and custom component mappings. Requires Node >=16.0.0. Maintained by a single contributor; release cadence is irregular.

Common errors

error Error: Cannot find module 'fumadocs-transpiler' ↓

cause Missing local install or incorrect import path.

fix

Run 'npm install fumadocs-transpiler' in your project directory.

error SyntaxError: Unexpected identifier 'callout' ↓

cause Invalid annotation syntax, e.g., '::: callout' instead of ':::callout'.

fix

Use ':::callout{type="info"}' without spaces after colons.

error TypeError: transpile is not a function ↓

cause Default import used instead of named import.

fix

Use import { transpile } from 'fumadocs-transpiler'.

error Error: Input directory does not exist: ./docs ↓

cause Specified input path is incorrect.

fix

Verify the directory exists and path is correct; use absolute paths if unsure.

Warnings

breaking v1.0.0 removed CommonJS support; migration to ESM only. ↓

fix Use import instead of require(). Ensure package.json has "type": "module" or use .mjs extension.

gotcha Triple-colon syntax must not have leading/trailing spaces after colons; e.g., '::: callout' is invalid. ↓

fix Use exact syntax ':::callout{type="info"}' without spaces after colons.

deprecated The --description CLI flag is deprecated in v1.3.0; use frontmatter YAML instead. ↓

fix Add 'description: ...' directly in the Markdown frontmatter instead of CLI flag.

gotcha Auto title extraction removes the first # heading from output; if you need to keep the heading, disable extraction. ↓

fix Set 'extractTitle: false' in options to preserve the heading.

breaking Version 0.9.0 changed default output extension from .mdx to .tsx. Existing workflows may break. ↓

fix Use --extension .mdx CLI flag to override, or update import statements in generated files.

gotcha Reverse transpilation does not support all Fumadocs features; complex MDX may fail. ↓

fix Preview with --dry-run before applying reverse; manual adjustments may be needed.

Install

npm install fumadocs-transpiler

yarn add fumadocs-transpiler

pnpm add fumadocs-transpiler

Imports

transpile

wrong

const transpile = require('fumadocs-transpiler')

correct

import { transpile } from 'fumadocs-transpiler'

ESM-only since v1. No default export; use named import.

transpileFile

wrong

import transpileFile from 'fumadocs-transpiler'

correct

import { transpileFile } from 'fumadocs-transpiler'

Use named import, not default.

reverseTranspile

wrong

const { reverseTranspile } = require('fumadocs-transpiler')

correct

import { reverseTranspile } from 'fumadocs-transpiler'

Reverse conversion from MDX to annotated Markdown. ESM only.

Quickstart

Shows ESM import and basic transpilation of a Markdown string with a callout annotation.

import { transpile } from 'fumadocs-transpiler';

const result = transpile(`
---
title: Example
---
:::callout{type="info"}
This is an info callout.
:::
`, {
  components: {
    callout: true,
    tabs: false
  }
});

console.log(result);
// Output: React component source code