Registry / web-framework / fumadocs-transpiler

fumadocs-transpiler

library1.3.0jsnpmunverified

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.

web-framework serialization

npm install fumadocs-transpiler

github ↗package ↗

INSTALL

IMPORT

SIG · FUMADOCS-TRANSPILE

fumadocs-transpiler

web-frameworkjavascriptv1.3.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

transpile

✓ import { transpile } from 'fumadocs-transpiler'

✗ const transpile = require('fumadocs-transpiler')

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

transpileFile

✓ import { transpileFile } from 'fumadocs-transpiler'

✗ import transpileFile from 'fumadocs-transpiler'

Use named import, not default.

reverseTranspile

✓ import { reverseTranspile } from 'fumadocs-transpiler'

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

Reverse conversion from MDX to annotated Markdown. ESM only.

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

Debug

Known issues

breakingv1.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.

affects: >=1.0.0

gotchaTriple-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.

affects: >=0.1.0

deprecatedThe --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.

affects: >=1.3.0

gotchaAuto 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.

affects: >=0.5.0

breakingVersion 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.

affects: >=0.9.0

gotchaReverse transpilation does not support all Fumadocs features; complex MDX may fail.

fix

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

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'fumadocs-transpiler'

Missing local install or incorrect import path.

fix

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

SyntaxError: Unexpected identifier 'callout'

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

fix

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

TypeError: transpile is not a function

Default import used instead of named import.

fix

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

Error: Input directory does not exist: ./docs

Specified input path is incorrect.

fix

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

Upgrade

Version history

1.3.0latest on npm

Audit

Dependencies

reactoptionalGenerated output is React components; runtime dependency for rendering.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/jagjeevanak/fumadocs-transpiler ↗

packagehttps://www.npmjs.com/package/fumadocs-transpiler ↗