vitepress-plugin-external-markdown

Materialize Markdown files outside a VitePress srcDir as generated Markdown pages inside srcDir.

This plugin copies external Markdown into a generated directory so VitePress can route it as normal pages. The same resolver drives generated files, sidebar items, nav items, and item metadata.

Documentation

• English: Getting started, Examples
• 日本語: はじめに, 例

Run the VitePress docs locally:

pnpm docs:dev

The documentation site is built with VitePress and deployed to GitHub Pages from the main branch:

https://jabelic-works.github.io/vitepress-plugin-external-markdown/

Install

pnpm add -D vitepress-plugin-external-markdown

Package: https://www.npmjs.com/package/vitepress-plugin-external-markdown

Usage

import { defineConfig } from 'vitepress'
import { externalMarkdown, getExternalMarkdownSidebar } from 'vitepress-plugin-external-markdown'

const externalMarkdownOptions = {
  srcDir: 'src',
  sources: [
    {
      baseDir: '../packages',
      pattern: '**/*.md',
    },
  ],
  outDir: 'generated/external',
  routeBase: '/generated/external/',
  copyAssets: [
    {
      baseDir: '../packages',
      pattern: 'images/**/*',
      outDir: 'generated/external',
    },
  ],
  resolveMarkdown(ctx) {
    return {
      slug: ctx.relativePath.replace(/\/index\.md$/, '').replace(/\.md$/, ''),
      title: ctx.title,
      text: ctx.title,
      order: ctx.relativePath,
      sidebar: true,
    }
  },
}

export default defineConfig({
  srcDir: 'src',
  vite: {
    plugins: [externalMarkdown(externalMarkdownOptions)],
  },
  themeConfig: {
    sidebar: {
      '/generated/external/': [
        {
          text: 'External Markdown',
          items: getExternalMarkdownSidebar(externalMarkdownOptions),
        },
      ],
    },
  },
})

If the VitePress command is run from a directory other than the VitePress project root, set root in the options used by the helpers:

const externalMarkdownOptions = {
  root: new URL('..', import.meta.url).pathname,
  // ...
}

Generated files

Generated files are written under srcDir/outDir, for example:

docs/
  src/
    generated/
      external/
        guide.md

Add the generated directory to .gitignore:

docs/src/generated/

Generated Markdown is a build artifact. Deployments should run vitepress build with this plugin enabled so the files are regenerated before VitePress builds the site.

Assets configured with copyAssets are also materialized under srcDir. Matched files keep their path relative to baseDir; Markdown links are not rewritten.

The plugin writes a marker file named .vitepress-plugin-external-markdown. Existing non-empty directories without that marker are not cleaned.

API

externalMarkdown(options)
getExternalMarkdownItems(options)
getExternalMarkdownSidebar(options)
getExternalMarkdownNav(options)

resolveMarkdown(ctx) may return false to skip a source file.

MVP limitations

This package intentionally does not rewrite relative links, create virtual routes, read remote Markdown, support MDX, or infer package docs automatically.