VitePress how-to

Documentation as two VitePress roots, both using root-package VitePress and Mermaid.

Tree	Audience	Scripts
docs/	Full internal handbook	docs:dev / docs:build / docs:preview
docs-public/	Public engineering notes (this site)	docs:public:*

Configs use .mts when the root package is CommonJS.

Install

pnpm add -D vitepress
pnpm add -D mermaid vitepress-plugin-mermaid   # diagrams
# Optional scaffold:
pnpm exec vitepress init

Commands

pnpm run docs:dev
pnpm run docs:build
pnpm run docs:public:dev
pnpm run docs:public:build     # → docs-public/.vitepress/dist

Implementation examples

Config with Mermaid

import { defineConfig } from 'vitepress';
import { withMermaid } from 'vitepress-plugin-mermaid';

export default withMermaid(
  defineConfig({
    title: 'Frontend Corner',
    cleanUrls: true,
    themeConfig: {
      nav: [{ text: 'Tooling', link: '/tooling/' }],
      sidebar: [
        {
          text: 'Tooling',
          items: [{ text: 'ESLint', link: '/tooling/eslint' }],
        },
      ],
    },
  })
);

Add a page

1. Create docs-public/tooling/my-tool.md.
2. Register in .vitepress/config.mts nav/sidebar.
3. Link with clean URLs: [My tool](/tooling/my-tool).
4. pnpm run docs:public:dev.

Scripts

{
  "scripts": {
    "docs:public:dev": "vitepress dev docs-public",
    "docs:public:build": "vitepress build docs-public",
    "docs:public:preview": "vitepress preview docs-public"
  }
}

Ignore **/.vitepress/dist/** and cache/** in ESLint, Prettier, and git.

Deploy

Separate Vercel project, Git deploy, output docs-public/.vitepress/dist — Publishing · Vercel.