vite-plugin-tdoc

2.0.4 verified Mon Apr 27 auth: no javascript

vite-plugin-tdoc (version 2.0.4) is a Vite plugin that transforms Markdown files into anything (e.g., HTML, Vue components) during the build process. Inspired by VitePress, it provides hooks for custom Markdown processing using markdown-it and its ecosystem (containers, attributes, anchors, TOC). It supports before/render/after transforms and can integrate additional Vite plugins. Released under MIT license. The plugin is actively maintained, with a focus on flexibility and developer control over Markdown transformation.

Common errors

error SyntaxError: Unexpected token 'export' ↓

cause Using CommonJS require() to load vite-plugin-tdoc in a CJS context.

fix

Switch vite.config to ES module (type: 'module' in package.json) and use import syntax.

error Error: Cannot find module 'markdown-it-container' ↓

cause Optional peer dependency markdown-it-container not installed.

fix

Install the optional dependencies: npm install markdown-it-container markdown-it-attrs markdown-it-anchor markdown-it-toc-done-right

error TypeError: md.use is not a function ↓

cause Trying to call md.use before markdown-it is initialized in config callback.

fix

Use the config callback correctly: config(md) { md.use(require('markdown-it-emoji')) }

Warnings

gotcha Using require() in config file will cause ESM/CJS mismatch in Vite. ↓

fix Use dynamic import() instead of require() in config, or mark package as type: module.

gotcha markdown-it-attrs may conflict with markdown-it-container syntax if both are used carelessly. ↓

fix Ensure custom container syntax does not interfere with attribute syntax; test combinations.

deprecated Options like 'markdown.anchor' and 'markdown.toc' may be deprecated in future versions. ↓

fix Check release notes for migration to direct markdown-it plugin usage.

gotcha The plugin does not work with CommonJS Vite configs (e.g., vite.config.js using module.exports). ↓

fix Use ES module syntax (export default) in vite config.

gotcha Transforms 'before', 'render', 'after' must return a string or undefined; returning null/object may break. ↓

fix Always return a string from transform hooks or undefined to skip modification.

Install

npm install vite-plugin-tdoc

yarn add vite-plugin-tdoc

pnpm add vite-plugin-tdoc

Imports

default

wrong

const vitePluginTdoc = require('vite-plugin-tdoc')

correct

import vitePluginTdoc from 'vite-plugin-tdoc'

ESM only; CommonJS require() will fail in Vite.

vitePluginTdoc

wrong

import { vitePluginTdoc } from 'vite-plugin-tdoc'

correct

import vitePluginTdoc from 'vite-plugin-tdoc'

Default export only, not named.

Type definitions
```
import type { Options } from 'vite-plugin-tdoc'
```
TypeScript users can import Options type for configuration.

Quickstart

Shows basic Vite config with vitePluginTdoc, enabling line numbers, anchor links, custom markdown-it plugins, and a before transform to strip HTML comments.

// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import vitePluginTdoc from 'vite-plugin-tdoc'

export default defineConfig({
  plugins: [
    vue(),
    vitePluginTdoc({
      markdown: {
        lineNumbers: true,
        anchor: { permalink: true },
        config(md) {
          md.use(require('markdown-it-emoji'))
        }
      },
      transforms: {
        before({ source }) {
          return source.replace(/<!--.*?-->/gs, '')
        }
      }
    })
  ]
})