docs: render diagram using mermaid (#940)

![image.png](https://app.graphite.com/user-attachments/assets/f0441ecb-1156-4a4b-a19f-43c349ec4a54.png)

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: branchseer

docs/.vitepress/config.mts

@@ -3,6 +3,7 @@ import { resolve } from 'node:path';
 import type { VoidZeroThemeConfig } from '@voidzero-dev/vitepress-theme';
 import { extendConfig } from '@voidzero-dev/vitepress-theme/config';
 import { defineConfig, type HeadConfig } from 'vitepress';
+import { withMermaid } from 'vitepress-plugin-mermaid';
 
 const taskRunnerGuideItems = [
   {
@@ -76,136 +77,141 @@ const guideSidebar = [
 ];
 
 export default extendConfig(
-  defineConfig({
-    title: 'Vite+',
-    titleTemplate: ':title | The Unified Toolchain for the Web',
-    description: 'The Unified Toolchain for the Web',
-    cleanUrls: true,
-    head: [
-      ['link', { rel: 'icon', type: 'image/svg+xml', href: '/favicon.svg' }],
-      [
-        'link',
-        {
-          rel: 'preconnect',
-          href: 'https://fonts.gstatic.com',
-          crossorigin: 'true',
-        },
-      ],
-      ['meta', { name: 'theme-color', content: '#7474FB' }],
-      ['meta', { property: 'og:type', content: 'website' }],
-      ['meta', { property: 'og:site_name', content: 'Vite+' }],
-      ['meta', { name: 'twitter:card', content: 'summary_large_image' }],
-      ['meta', { name: 'twitter:site', content: '@voidzerodev' }],
-      [
-        'script',
-        {
-          src: 'https://cdn.usefathom.com/script.js',
-          'data-site': 'JFDLUWBH',
-          'data-spa': 'auto',
-          defer: '',
-        },
+  withMermaid(
+    defineConfig({
+      title: 'Vite+',
+      titleTemplate: ':title | The Unified Toolchain for the Web',
+      description: 'The Unified Toolchain for the Web',
+      cleanUrls: true,
+      head: [
+        ['link', { rel: 'icon', type: 'image/svg+xml', href: '/favicon.svg' }],
+        [
+          'link',
+          {
+            rel: 'preconnect',
+            href: 'https://fonts.gstatic.com',
+            crossorigin: 'true',
+          },
+        ],
+        ['meta', { name: 'theme-color', content: '#7474FB' }],
+        ['meta', { property: 'og:type', content: 'website' }],
+        ['meta', { property: 'og:site_name', content: 'Vite+' }],
+        ['meta', { name: 'twitter:card', content: 'summary_large_image' }],
+        ['meta', { name: 'twitter:site', content: '@voidzerodev' }],
+        [
+          'script',
+          {
+            src: 'https://cdn.usefathom.com/script.js',
+            'data-site': 'JFDLUWBH',
+            'data-spa': 'auto',
+            defer: '',
+          },
+        ],
       ],
-    ],
-    vite: {
-      resolve: {
-        tsconfigPaths: true,
-        alias: {
-          '@local-assets': resolve(__dirname, 'theme/assets'),
-          '@layouts': resolve(__dirname, 'theme/layouts'),
-        },
-      },
-    },
-    themeConfig: {
-      variant: 'viteplus' as VoidZeroThemeConfig['variant'],
-      nav: [
-        {
-          text: 'Guide',
-          link: '/guide/',
-          activeMatch: '^/guide/',
-        },
-        {
-          text: 'Config',
-          link: '/config/',
-          activeMatch: '^/config/',
-        },
-        {
-          text: 'Resources',
-          items: [
-            { text: 'GitHub', link: 'https://github.com/voidzero-dev/vite-plus' },
-            { text: 'Releases', link: 'https://github.com/voidzero-dev/vite-plus/releases' },
-            {
-              text: 'Announcement',
-              link: 'https://voidzero.dev/posts/announcing-vite-plus-alpha',
-            },
-            {
-              text: 'Contributing',
-              link: 'https://github.com/voidzero-dev/vite-plus/blob/main/CONTRIBUTING.md',
-            },
+      vite: {
+        resolve: {
+          tsconfigPaths: true,
+          alias: [
+            { find: '@local-assets', replacement: resolve(__dirname, 'theme/assets') },
+            { find: '@layouts', replacement: resolve(__dirname, 'theme/layouts') },
+            // dayjs ships CJS by default; redirect to its ESM build so
+            // mermaid (imported via vitepress-plugin-mermaid) works in dev
+            { find: /^dayjs$/, replacement: 'dayjs/esm' },
           ],
         },
-      ],
-      sidebar: {
-        '/guide/': guideSidebar,
-        '/config/': [
+      },
+      themeConfig: {
+        variant: 'viteplus' as VoidZeroThemeConfig['variant'],
+        nav: [
+          {
+            text: 'Guide',
+            link: '/guide/',
+            activeMatch: '^/guide/',
+          },
+          {
+            text: 'Config',
+            link: '/config/',
+            activeMatch: '^/config/',
+          },
           {
-            text: 'Configuration',
+            text: 'Resources',
             items: [
-              { text: 'Configuring Vite+', link: '/config/' },
-              { text: 'Run', link: '/config/run' },
-              { text: 'Format', link: '/config/fmt' },
-              { text: 'Lint', link: '/config/lint' },
-              { text: 'Test', link: '/config/test' },
-              { text: 'Build', link: '/config/build' },
-              { text: 'Pack', link: '/config/pack' },
-              { text: 'Staged', link: '/config/staged' },
+              { text: 'GitHub', link: 'https://github.com/voidzero-dev/vite-plus' },
+              { text: 'Releases', link: 'https://github.com/voidzero-dev/vite-plus/releases' },
+              {
+                text: 'Announcement',
+                link: 'https://voidzero.dev/posts/announcing-vite-plus-alpha',
+              },
+              {
+                text: 'Contributing',
+                link: 'https://github.com/voidzero-dev/vite-plus/blob/main/CONTRIBUTING.md',
+              },
             ],
           },
         ],
-      },
-      socialLinks: [
-        { icon: 'github', link: 'https://github.com/voidzero-dev/vite-plus' },
-        { icon: 'x', link: 'https://x.com/voidzerodev' },
-        { icon: 'discord', link: 'https://discord.gg/cC6TEVFKSx' },
-        { icon: 'bluesky', link: 'https://bsky.app/profile/voidzero.dev' },
-      ],
-      outline: {
-        level: [2, 3],
-      },
-      search: {
-        provider: 'local',
-      },
-    },
-    transformHead({ page, pageData }) {
-      const url = 'https://viteplus.dev/' + page.replace(/\.md$/, '').replace(/index$/, '');
-
-      const canonicalUrlEntry: HeadConfig = [
-        'link',
-        {
-          rel: 'canonical',
-          href: url,
+        sidebar: {
+          '/guide/': guideSidebar,
+          '/config/': [
+            {
+              text: 'Configuration',
+              items: [
+                { text: 'Configuring Vite+', link: '/config/' },
+                { text: 'Run', link: '/config/run' },
+                { text: 'Format', link: '/config/fmt' },
+                { text: 'Lint', link: '/config/lint' },
+                { text: 'Test', link: '/config/test' },
+                { text: 'Build', link: '/config/build' },
+                { text: 'Pack', link: '/config/pack' },
+                { text: 'Staged', link: '/config/staged' },
+              ],
+            },
+          ],
         },
-      ];
-
-      const ogInfo: HeadConfig[] = [
-        ['meta', { property: 'og:title', content: pageData.frontmatter.title ?? 'Vite+' }],
-        [
-          'meta',
-          {
-            property: 'og:image',
-            content: `https://viteplus.dev/${pageData.frontmatter.cover ?? 'og.jpg'}`,
-          },
+        socialLinks: [
+          { icon: 'github', link: 'https://github.com/voidzero-dev/vite-plus' },
+          { icon: 'x', link: 'https://x.com/voidzerodev' },
+          { icon: 'discord', link: 'https://discord.gg/cC6TEVFKSx' },
+          { icon: 'bluesky', link: 'https://bsky.app/profile/voidzero.dev' },
         ],
-        ['meta', { property: 'og:url', content: url }],
-        [
-          'meta',
+        outline: {
+          level: [2, 3],
+        },
+        search: {
+          provider: 'local',
+        },
+      },
+      transformHead({ page, pageData }) {
+        const url = 'https://viteplus.dev/' + page.replace(/\.md$/, '').replace(/index$/, '');
+
+        const canonicalUrlEntry: HeadConfig = [
+          'link',
           {
-            property: 'og:description',
-            content: pageData.frontmatter.description ?? 'The Unified Toolchain for the Web',
+            rel: 'canonical',
+            href: url,
           },
-        ],
-      ];
+        ];
 
-      return [...ogInfo, canonicalUrlEntry];
-    },
-  }),
+        const ogInfo: HeadConfig[] = [
+          ['meta', { property: 'og:title', content: pageData.frontmatter.title ?? 'Vite+' }],
+          [
+            'meta',
+            {
+              property: 'og:image',
+              content: `https://viteplus.dev/${pageData.frontmatter.cover ?? 'og.jpg'}`,
+            },
+          ],
+          ['meta', { property: 'og:url', content: url }],
+          [
+            'meta',
+            {
+              property: 'og:description',
+              content: pageData.frontmatter.description ?? 'The Unified Toolchain for the Web',
+            },
+          ],
+        ];
+
+        return [...ogInfo, canonicalUrlEntry];
+      },
+    }),
+  ),
 );

docs/guide/run.md

@@ -225,10 +225,9 @@ When a command contains `vp run`, Vite Task inlines it as separate tasks instead
 
 Running `vp run ci` expands into three tasks:
 
-```
-┌────────┐   ┌────────┐   ┌────────┐
-│  lint  │──▶│  test  │──▶│ build  │
-└────────┘   └────────┘   └────────┘
+```mermaid
+graph LR
+  lint --> test --> build
 ```
 
 Flags also work inside nested scripts. For example, `vp run -r build` inside a script expands into individual build tasks for every package.

docs/package.json

@@ -9,8 +9,10 @@
   },
   "dependencies": {
     "@iconify/vue": "^5.0.0",
+    "mermaid": "^11.13.0",
     "reka-ui": "^2.7.0",
     "typewriter-effect": "^2.22.0",
+    "vitepress-plugin-mermaid": "^2.0.17",
     "vue": "^3.5.27",
     "vue3-carousel": "^0.16.0"
   },