@miyaoka/vite-plugin-doc-block

@miyaoka/vite-plugin-doc-block

Vite plugin to strip <doc> custom blocks from Vue SFC.

Write documentation directly in your Vue components. The plugin removes them during build, so they don't affect bundle size.

Install

pnpm add -D @miyaoka/vite-plugin-doc-block

Usage

// vite.config.ts
import { docBlockPlugin } from '@miyaoka/vite-plugin-doc-block'
import vue from '@vitejs/plugin-vue'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [docBlockPlugin(), vue()],
})

Note: Place docBlockPlugin() before other Vue-related plugins. This plugin must run before vite-plugin-vue-inspector (used by vite-plugin-vue-devtools), which would error when parsing HTML-like strings (e.g. <RouterView>) inside <doc> blocks.

Then you can write <doc> blocks in your Vue components:

<doc lang="md">
# MyComponent

This component displays user information.

## Props

- `userId` - The user ID to display

## Usage

Used in the user profile page.
</doc>

<script setup lang="ts">
const props = defineProps<{ userId: string }>()
</script>

<template>
  <div>{{ user.name }}</div>
</template>

The <doc> block will be removed during build.

Why

• Colocation: Keep documentation next to the code it describes
• Zero runtime cost: Stripped at build time
• IDE friendly: Documentation is visible when editing the component

Why not a simpler approach?

A common approach to ignore custom blocks is to return an empty module:

// This does NOT work with vite-plugin-vue-inspector
const vueDocsPlugin = {
  name: 'vue-docs',
  transform(_code, id) {
    if (!/vue&type=doc/.test(id))
      return
    return `export default ''`
  },
}

However, this doesn't solve the vite-plugin-vue-inspector issue. The inspector parses the SFC before this transform runs, and HTML-like strings inside <doc> blocks (e.g. <RouterView>) cause parsing errors.

This plugin uses enforce: 'pre' to run before the inspector and removes the content from the SFC source directly, preventing the error.

Dependency scan

Vite's dependency scanner does not run the normal plugin pipeline — it reads .vue files from disk and extracts <script> blocks with a regex. A literal <script> string inside a doc block (even in a markdown code span) would be misdetected as an opening tag and break the scan, skipping dependency pre-bundling.

To prevent this, the plugin also injects a scan-only plugin via optimizeDeps.rolldownOptions.plugins, which parses SFCs containing doc blocks with the real SFC parser and exposes each script block as its own module, mirroring Vite's built-in scan loader.

Note: This scan fix relies on Vite 8's rolldown-based scanner. On Vite 5–7 (esbuild-based scan) the option is ignored, so the scan issue remains there.

License

MIT