Registry / web-framework / vite-plugin-markdoc

vite-plugin-markdoc

library0.1.4jsnpmunverified

A Vite plugin that enables importing Markdoc (Stripe's Markdown-based documentation toolchain) files directly as JavaScript modules. Current stable version is 0.1.4, released as a pre-major version with no set release cadence. It uses @markdoc/markdoc under the hood to parse and transform .md files into renderable trees, which can then be rendered with Markdoc's HTML or React renderers. Key differentiators: built specifically for Vite (not Rollup/webpack), supports frontmatter, custom tags/nodes, and provides a first-class TypeScript shim for type-safe imports. Ideal for documentation sites built with Vite + React or Vue.

web-framework

npm install vite-plugin-markdoc

package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-MARKDO

vite-plugin-markdoc

web-frameworkjavascriptv0.1.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

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

default (markdoc function)

✓ import markdoc from 'vite-plugin-markdoc'

✗ const markdoc = require('vite-plugin-markdoc')

Package is ESM-only; CommonJS require() will fail. The default export is a function that returns a Vite plugin.

RenderableTreeNode

✓ import type { RenderableTreeNode } from '@markdoc/markdoc'

✗ import { RenderableTreeNode } from 'vite-plugin-markdoc'

Type is re-exported from @markdoc/markdoc, but the plugin does not export it directly. Import from @markdoc/markdoc.

Markdoc renderers

✓ import Markdoc from '@markdoc/markdoc'

✗ import Markdoc from 'vite-plugin-markdoc'

Markdoc itself is a separate package; vite-plugin-markdoc only provides the Vite integration.

Shows how to configure the plugin, add TypeScript shim for .md imports, and render Markdoc content as a React component.

// vite.config.ts import { defineConfig } from 'vite' import markdoc from 'vite-plugin-markdoc' export default defineConfig({ plugins: [markdoc()] }) // env.d.ts (or shims-vite.d.ts) declare module '*.md' { import type { RenderableTreeNode } from '@markdoc/markdoc' const node: RenderableTreeNode export default node } // src/App.tsx import content from './docs/hello.md' import Markdoc from '@markdoc/markdoc' import { renderReact } from '@markdoc/markdoc/react' function App() { const ReactComponent = renderReact(content) return <ReactComponent /> }

Debug

Known issues

gotchaImporting a .md file returns a RenderableTreeNode (object), not a string. You must use Markdoc renderers (react/nextjs/html) to render it.

fix

Use Markdoc.renderers.html(content) or @markdoc/markdoc-react for React.

affects: >=0.0.0

breakingvite-plugin-markdoc is pre-1.0 (0.1.4) and has no breaking change policy. Minor versions may introduce breaking changes.

fix

Pin to exact version and check changelog before upgrading.

affects: >=0.0.0

deprecatedThe package does not currently provide any deprecation warnings. Check for future releases.

fix

Stay updated with package releases.

affects: >=0.1.0

gotchaPlugin only works with Vite; not compatible with webpack or Rollup directly.

fix

Use Vite as your build tool.

affects: >=0.0.0

Errors

Common errors & fixes

Cannot find module 'vite-plugin-markdoc' or its corresponding type declarations.

The module is not installed or you are using TypeScript without a module declaration for .md files.

fix

Run npm install vite-plugin-markdoc -D and add a shim file (see TypeScript Shim section).

ERR_REQUIRE_ESM from vite-plugin-markdoc

Trying to require an ESM-only package with require() in CommonJS context.

fix

Convert your config to ESM (use import instead of require) or use dynamic import().

TypeError: markdoc is not a function

Importing vite-plugin-markdoc incorrectly (e.g., named import instead of default).

fix

Use import markdoc from 'vite-plugin-markdoc'.

Upgrade

Version history

0.1.4latest on npm

Audit

Dependencies

@markdoc/markdocrequiredCore Markdoc compiler used to parse and transform .md files

Agent activity

5 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://www.npmjs.com/package/vite-plugin-markdoc ↗