{"id":22731,"library":"vite-plugin-markdoc","title":"vite-plugin-markdoc","description":"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.","status":"active","version":"0.1.4","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","vite","frontmatter","markdown","react","vue","typescript"],"install":[{"cmd":"npm install vite-plugin-markdoc","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-markdoc","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-markdoc","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core Markdoc compiler used to parse and transform .md files","package":"@markdoc/markdoc","optional":false}],"imports":[{"note":"Package is ESM-only; CommonJS require() will fail. The default export is a function that returns a Vite plugin.","wrong":"const markdoc = require('vite-plugin-markdoc')","symbol":"default (markdoc function)","correct":"import markdoc from 'vite-plugin-markdoc'"},{"note":"Type is re-exported from @markdoc/markdoc, but the plugin does not export it directly. Import from @markdoc/markdoc.","wrong":"import { RenderableTreeNode } from 'vite-plugin-markdoc'","symbol":"RenderableTreeNode","correct":"import type { RenderableTreeNode } from '@markdoc/markdoc'"},{"note":"Markdoc itself is a separate package; vite-plugin-markdoc only provides the Vite integration.","wrong":"import Markdoc from 'vite-plugin-markdoc'","symbol":"Markdoc renderers","correct":"import Markdoc from '@markdoc/markdoc'"}],"quickstart":{"code":"// vite.config.ts\nimport { defineConfig } from 'vite'\nimport markdoc from 'vite-plugin-markdoc'\n\nexport default defineConfig({\n  plugins: [markdoc()]\n})\n\n// env.d.ts (or shims-vite.d.ts)\ndeclare module '*.md' {\n  import type { RenderableTreeNode } from '@markdoc/markdoc'\n  const node: RenderableTreeNode\n  export default node\n}\n\n// src/App.tsx\nimport content from './docs/hello.md'\nimport Markdoc from '@markdoc/markdoc'\nimport { renderReact } from '@markdoc/markdoc/react'\n\nfunction App() {\n  const ReactComponent = renderReact(content)\n  return <ReactComponent />\n}","lang":"typescript","description":"Shows how to configure the plugin, add TypeScript shim for .md imports, and render Markdoc content as a React component."},"warnings":[{"fix":"Use Markdoc.renderers.html(content) or @markdoc/markdoc-react for React.","message":"Importing a .md file returns a RenderableTreeNode (object), not a string. You must use Markdoc renderers (react/nextjs/html) to render it.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Pin to exact version and check changelog before upgrading.","message":"vite-plugin-markdoc is pre-1.0 (0.1.4) and has no breaking change policy. Minor versions may introduce breaking changes.","severity":"breaking","affected_versions":">=0.0.0"},{"fix":"Stay updated with package releases.","message":"The package does not currently provide any deprecation warnings. Check for future releases.","severity":"deprecated","affected_versions":">=0.1.0"},{"fix":"Use Vite as your build tool.","message":"Plugin only works with Vite; not compatible with webpack or Rollup directly.","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Run npm install vite-plugin-markdoc -D and add a shim file (see TypeScript Shim section).","cause":"The module is not installed or you are using TypeScript without a module declaration for .md files.","error":"Cannot find module 'vite-plugin-markdoc' or its corresponding type declarations."},{"fix":"Convert your config to ESM (use import instead of require) or use dynamic import().","cause":"Trying to require an ESM-only package with require() in CommonJS context.","error":"ERR_REQUIRE_ESM from vite-plugin-markdoc"},{"fix":"Use import markdoc from 'vite-plugin-markdoc'.","cause":"Importing vite-plugin-markdoc incorrectly (e.g., named import instead of default).","error":"TypeError: markdoc is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}