vitepress-plugin-html-image

A markdown-it plugin that normalizes relative src paths in raw HTML <img> tags inside VitePress.

Problem

VitePress processes Markdown-syntax images (![](./img/foo.png)) and picks them up in the asset pipeline. Raw HTML inside Markdown (<img src="img/foo.png">), however, stays untouched, Vite does not see those paths as assets and they break in production.

The typical source of the problem is documents converted from DocBook: they contain tables with <img> inside HTML blocks.

Solution

The plugin walks every html_block and html_inline token from markdown-it and for each <img src="...">:

• When the path is relative (img/foo.png), it adds the ./ prefix
• Decodes %NN in the path with decodeURIComponent
• Adds data-vite-ignore so Vite does not try to run the path through its asset pipeline (relative paths resolve as regular page resources)
• Skips <img> tags inside <pre> blocks

Installation

npm install @ampernic/vitepress-plugin-html-image

Usage

// .vitepress/config.ts
import { defineConfig } from 'vitepress'
import { htmlImagePlugin } from '@ampernic/vitepress-plugin-html-image'

export default defineConfig({
  markdown: {
    config: (md) => {
      md.use(htmlImagePlugin)
    },
  },
})

Handled cases

Input src	Result
img/foo.png	./img/foo.png + data-vite-ignore
./img/foo.png	./img/foo.png + data-vite-ignore
../assets/bar.svg	../assets/bar.svg + data-vite-ignore
/absolute/path.png	unchanged
https://example.com/img.png	unchanged
data:image/...	unchanged