vite-plugin-markdoc

0.1.4 verified Mon Apr 27 auth: no javascript

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.

Common errors

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

cause 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).

error ERR_REQUIRE_ESM from vite-plugin-markdoc ↓

cause 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().

error TypeError: markdoc is not a function ↓

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

fix

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

Warnings

gotcha Importing 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.

breaking vite-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.

deprecated The package does not currently provide any deprecation warnings. Check for future releases. ↓

fix Stay updated with package releases.

gotcha Plugin only works with Vite; not compatible with webpack or Rollup directly. ↓

fix Use Vite as your build tool.

Install

npm install vite-plugin-markdoc

yarn add vite-plugin-markdoc

pnpm add vite-plugin-markdoc

Imports

default (markdoc function)
wrong
```
const markdoc = require('vite-plugin-markdoc')
```
correct
```
import markdoc from 'vite-plugin-markdoc'
```
Package is ESM-only; CommonJS require() will fail. The default export is a function that returns a Vite plugin.
RenderableTreeNode
wrong
```
import { RenderableTreeNode } from 'vite-plugin-markdoc'
```
correct
```
import type { RenderableTreeNode } from '@markdoc/markdoc'
```
Type is re-exported from @markdoc/markdoc, but the plugin does not export it directly. Import from @markdoc/markdoc.
Markdoc renderers
wrong
```
import Markdoc from 'vite-plugin-markdoc'
```
correct
```
import Markdoc from '@markdoc/markdoc'
```
Markdoc itself is a separate package; vite-plugin-markdoc only provides the Vite integration.

Quickstart

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 />
}