vitepress-theme-app-docs

🌎 English · 🇪🇸 Español

Reusable VitePress theme package for product and application documentation sites. It ships the custom visual layer, globally registered authoring components, Mermaid integration, and the interactive VTDocDiagramPresenter system that was originally embedded in a single docs site.

Preview

Desktop — light mode

Desktop — dark mode

Neon preset — dark mode

The Neon feature preset switches the diagram to a State Diagram and applies a neon glow style (dark background, cyan and purple highlights).

Controls panel

Mobile — light mode

| Top of page | Diagram | |:-----------:|:-------:| | | |

Mobile — dark mode

What is included

• Custom VitePress theme entry (index.ts)
• Shared theme styles (style.css) with CSS variable tokens for full callout colour customisation
• Global authoring components for cards, callouts, steps, tabs, accordions, and diagrams — all prefixed VTDoc* to avoid naming collisions
• ThemeConfig type extending DefaultTheme.Config for typed VitePress config
• GlobalComponents augmentation so Volar autocompletes <VTDoc*> components in templates and Markdown
• Mermaid toolbar integration through vitepress-mermaid-renderer
• VTDocDiagramPresenter for animated Mermaid walkthroughs with modular adapter support (Flowchart, State, Sequence, Class, ER)
• VTDocMermaidPlayground for interactive Mermaid prop tuning
• VTDocMindmap for interactive Markmap mindmaps with pan, zoom, fullscreen, export, and step-by-step depth navigation
• VTDocMindmapPlayground for interactive Markmap prop tuning
• Article Print Button: Integrated into the page header for perfectly scaled document printing, with specialized re-layout logic for complex diagrams.
• Extensible i18n System: Localize all theme strings (tooltips, ARIA labels, controls) with deep-merge resolution and built-in English and Spanish support.
• Detailed documentation and guides in docs/guide/
• A local preview site in docs/ to test the package in a real VitePress instance

Guides

For detailed instructions and examples, refer to the following guides. You can also view them interactively by running the local preview site with pnpm docs:dev.

• 🚀 Getting Started — Installation and basic setup.
• 🧩 Components — Reference for all global VTDoc* components.
• 📊 Mermaid Diagrams — Deep dive into the animation engine and props.
• 🛠️ Custom Adapters — How to support new Mermaid diagram types.
• 🧠 Mindmaps — Rendering interactive mindmaps with Markmap.
• 🌎 Internationalization — Localizing theme strings and UI.
• 🎮 Playground — Using the interactive tuning sandbox.

Installation

Install the package and satisfy its peer dependencies in the consuming docs site:

pnpm add vitepress-theme-app-docs
pnpm add vitepress vue mermaid vitepress-mermaid-renderer gsap @heroicons/vue

The package is intentionally source-first. Consumers load the exported TypeScript and Vue source files directly through VitePress/Vite — no pre-compilation step is needed.

Requirements

• Node.js >=22
• TypeScript >=5.7 if you consume the bundled .d.ts files. The runtime types under dist-runtime/ use TS 6.x rewriteRelativeImportExtensions, so older TypeScript needs "moduleResolution": "bundler" (the VitePress default). Declared as an optional peer dependency.
• Peer deps: vitepress, vue, mermaid, vitepress-mermaid-renderer, gsap, @heroicons/vue.

⚠️ Upgrading from 0.6.x to 0.7.0 — breaking change

The wildcard subpath vitepress-theme-app-docs/components/* has been removed. Only the public .vue components are exported by path now; internal helpers (vt-doc-steps-context, diagram adapters, composables, shared/*, internal/*, VTDocPageHeader.vue, etc.) no longer resolve through bare-specifier imports.

Migrate by importing from the package root:

// before (broken in 0.7.0)
import VTDocCard from 'vitepress-theme-app-docs/components/VTDocCard.vue'
import { stepsKey } from 'vitepress-theme-app-docs/components/vt-doc-steps-context'

// after
import { VTDocCard } from 'vitepress-theme-app-docs'
import type { DocStepsType, ThemeConfig } from 'vitepress-theme-app-docs'

See CHANGELOG.md for the full list of removed paths.

Use the theme in VitePress

If the package should become the site theme as-is:

// docs/.vitepress/theme/index.ts
import Theme from 'vitepress-theme-app-docs'

export default Theme

If the site needs to extend the package with local components or hooks:

// docs/.vitepress/theme/index.ts
import type { Theme } from 'vitepress'
import AppDocsTheme from 'vitepress-theme-app-docs'

export default {
  extends: AppDocsTheme,
  enhanceApp(ctx) {
    AppDocsTheme.enhanceApp?.(ctx)

    // Register site-specific components here.
  },
} satisfies Theme

Typed theme configuration

This package extends the VitePress default theme. Every standard VitePress field (nav, sidebar, logo, search, socialLinks, etc.) remains fully available — this package only adds three extra fields on top. If you are new to VitePress, start with the VitePress guide and the site config reference.

Import ThemeConfig and appDocsVitePlugin from the ./config subpath. The plugin handles Vite dependency pre-bundling for all transitive CJS packages pulled in by mermaid (e.g. dayjs) so you do not need to configure optimizeDeps manually:

// docs/.vitepress/config.ts
import { defineConfigWithTheme } from 'vitepress'
import type { ThemeConfig } from 'vitepress-theme-app-docs/config'
import { appDocsVitePlugin } from 'vitepress-theme-app-docs/config'

export default defineConfigWithTheme<ThemeConfig>({
  vite: {
    plugins: [appDocsVitePlugin()],
  },
  themeConfig: {
    // All standard VitePress fields remain fully typed
    nav: [...],
    sidebar: [...],
    // Theme-specific field
    pageHeader: true,
  }
})

ThemeConfig extends DefaultTheme.Config, so every built-in VitePress field remains available and typed. See the default theme config reference for the full list of standard fields.

themeConfig fields added by this package

| Field | Type | Default | Description | | --- | --- | --- | --- | | pageHeader | boolean | true | Show the styled title + description header above doc content. Override per-page with pageHeader: false in frontmatter. | | mermaid.toolbar | boolean | true | Show the zoom, download, and fullscreen toolbar above rendered Mermaid diagrams. | | mermaid.downloadFormat | 'svg' \| 'png' | 'svg' | File format used when the download button is clicked. | | themeTransition | boolean | true | Enable the diagonal curtain View Transition when toggling light/dark mode. Degrades gracefully when the browser does not support the View Transitions API. | | i18n | I18nConfig | {} | Internationalization configuration for UI strings. Supports built-in English and Spanish. |

Theme behaviour

The exported theme already:

• extends the VitePress default theme
• imports style.css
• wires Mermaid rendering with a toolbar and fullscreen dialog support
• registers the authoring components globally as VTDoc*
• injects a styled page header before document content, reading title and description from frontmatter
• implements a diagonal curtain View Transition on the light/dark appearance toggle

Global components

All components below are registered by enhanceApp, so they are available directly inside Markdown without importing. Volar resolves them via the bundled GlobalComponents augmentation.

| Component | Props | Purpose | | --- | --- | --- | | VTDocNote | none | Violet callout box (docs) | | VTDocTip | none | Green callout box (docs) | | VTDocWarning | none | Amber callout box (docs) | | VTDocInfo | none | Blue callout box (docs) | | VTDocCheck | none | Success callout box (docs) | | VTDocCardGroup | cols?: string \| number | Responsive card grid (docs) | | VTDocCard | title: string, icon?: string, href?: string | Linked or static feature card (docs) | | VTDocSteps | none | Wrapper for ordered visual steps (docs) | | VTDocStep | title: string | Single numbered step (docs) | | VTDocTabs | variant?: 'underline' \| 'pills' \| 'segmented' | Tab set container (docs) | | VTDocTab | title: string | One tab panel (docs) | | VTDocAccordionGroup | none | Accordion wrapper (docs) | | VTDocAccordion | title: string | One collapsible section (docs) | | VTDocMindmap | code: string | Interactive Markdown mindmap (docs) | | VTDocDiagramPresenter | see dedicated section below | Animated Mermaid presenter (docs) | | VTDocMermaidPlayground | none | Interactive VTDocDiagramPresenter sandbox (docs) | | VTDocMindmapPlayground | none | Interactive VTDocMindmap sandbox (docs) |

Card icon names

VTDocCard supports the following icon keys:

camera, image, video, list-check, rocket, browser, file-csv, gear, language, pen, shield-halved, sliders, sun, upload

Individual component imports

All components are also available as named exports for direct import in Vue SFCs or custom layouts:

import {
  VTDocCard,
  VTDocNote,
  VTDocDiagramPresenter,
} from 'vitepress-theme-app-docs'

Authoring examples

Callouts

<VTDocNote>Use notes for contextual guidance.</VTDocNote>
<VTDocTip>Use tips for recommended actions.</VTDocTip>
<VTDocWarning>Use warnings for risk or prerequisites.</VTDocWarning>
<VTDocInfo>Use info boxes for neutral background detail.</VTDocInfo>
<VTDocCheck>Use checks for success outcomes.</VTDocCheck>

Cards

<VTDocCardGroup :cols="3">
  <VTDocCard title="Quickstart" icon="rocket" href="/guide/getting-started">
    Install the package and wire it into a VitePress site.
  </VTDocCard>
  <VTDocCard title="Components" icon="list-check" href="/guide/components">
    Review all globally registered authoring primitives.
  </VTDocCard>
  <VTDocCard title="Diagrams" icon="sliders" href="/guide/diagram-presenter">
    Animate Mermaid diagrams with timeline controls.
  </VTDocCard>
</VTDocCardGroup>

Steps

<VTDocSteps>
  <VTDocStep title="Install the package">Add the package and peer dependencies.</VTDocStep>
  <VTDocStep title="Wrap the theme">Export the package theme from `.vitepress/theme/index.ts`.</VTDocStep>
  <VTDocStep title="Write docs">Use the global components inside Markdown pages.</VTDocStep>
</VTDocSteps>

Tabs

<VTDocTabs>
  <VTDocTab title="pnpm">

```bash
pnpm add vitepress-theme-app-docs
```

  </VTDocTab>
  <VTDocTab title="npm">

```bash
npm install vitepress-theme-app-docs
```

  </VTDocTab>
</VTDocTabs>

Accordions

<VTDocAccordionGroup>
  <VTDocAccordion title="Why a package?">
    To keep the theme reusable across multiple VitePress sites.
  </VTDocAccordion>
  <VTDocAccordion title="How is it published?">
    Use the provided `.npmrc` template and publish scripts.
  </VTDocAccordion>
</VTDocAccordionGroup>

Customising callout colours

The callout components use CSS custom properties. Override any token in your own CSS file to reskin them without touching the package source:

/* docs/.vitepress/theme/custom.css */
:root {
  --doc-c-note-bg: #f0f4ff;
  --doc-c-note-border: #3b5bdb;
  --doc-c-note-text: #1e3a8a;
  --doc-c-note-icon: #3b5bdb;
}

.dark {
  --doc-c-note-bg: rgba(59, 91, 219, 0.12);
  --doc-c-note-text: #a5b4fc;
  --doc-c-note-icon: #a5b4fc;
}

Available tokens follow the pattern --doc-c-{type}-{role} where type is note, tip, warning, info, or check, and role is bg, border, text, or icon.

Multi-language support

The theme includes built-in flag icons for English (GB) and Spanish (ES).

Adding custom languages

The theme uses a Master Variable pattern to make adding languages easy. If you want to add support for a new language (e.g., French):

1. Configure the new locale in your docs/.vitepress/config.ts (standard VitePress procedure).
2. Add these two lines to your custom CSS to "wire" the flag:

/* 1. Set the flag for the navbar button when this language is active */
html[lang^='fr'] { --vt-current-flag: url('/path-to-fr-flag.svg'); }

/* 2. Set the flag for the items in the language switcher menu */
[href*='/fr/'] { --vt-item-flag: url('/path-to-fr-flag.svg'); }

Overriding default flags

You can override the built-in flags by redefining the same variables in your CSS:

/* Override English flag */
html[lang^='en'] { --vt-current-flag: url('/custom-en.svg'); }
[href='/'], [href^='/guide/'], [href*='/en/'] { --vt-item-flag: url('/custom-en.svg'); }

/* Override Spanish flag */
html[lang^='es'] { --vt-current-flag: url('/custom-es.svg'); }
[href*='/es/'] { --vt-item-flag: url('/custom-es.svg'); }

Mermaid support

Regular Mermaid code fences are rendered through vitepress-mermaid-renderer, and the theme configures:

• light/dark aware Mermaid themes
• zoom and download toolbar controls
• fullscreen dialog mode
• a reset-on-fullscreen autofit fix

Example:

VTDocDiagramPresenter

VTDocDiagramPresenter is intended for walkthroughs and storytelling with Mermaid diagrams. It adds animated node and edge playback, captioning, fullscreen zoom, export, keyboard shortcuts, minimap, and adapter-aware features.

Props

| Prop | Type | Default | Notes | | --- | --- | --- | --- | | code | string | required | Mermaid source | | preset | 'auto' \| 'soft' \| 'neon' | 'auto' | auto follows VitePress dark mode | | controls | boolean | true | Show inline toolbar | | showBadge | boolean | false | Show adapter label | | autoPlay | 'none' \| 'nodes' \| 'edges' \| 'all' \| 'intersect' | 'none' | Playback strategy | | highlight | string[] | [] | Node keys to highlight | | highlightMode | 'pulse' \| 'glow' | 'pulse' | Highlight style | | speed | 'slow' \| 'normal' \| 'fast' | 'normal' | Initial playback speed | | loop | boolean | false | Loop playback | | caption | string | '' | Optional figure caption | | phaseNav | boolean | false | Guided phase navigation mode | | spotlight | boolean | false | Hover-based branch spotlight | | timing | object | internal defaults | Duration overrides in seconds |

Default timing values:

{
  nodeDuration: 0.45,
  nodeStagger: 0.11,
  edgeDuration: 0.7,
  edgeStagger: 0.09,
  levelGap: 0.1,
}

Custom Adapters

The system is built on a modular architecture where each diagram type has its own adapter. You can extend the system by creating your own adapters to support new Mermaid diagram types or customize animation logic.

Check the Custom Adapters Guide for implementation details.

TypeScript Support

The package provides strict typing for all its components and composables. Internal logic has been refactored to ensure a robust developer experience with minimal use of any or unknown.

Events

| Event | Meaning | | --- | --- | | ready | Diagram is rendered and ready for interaction | | play-start | Playback started | | play-complete | Playback finished |

Exposed methods

VTDocDiagramPresenter exposes the following methods for advanced orchestration:

• play()
• playNodes()
• playEdges()
• pause()
• resume()
• togglePause()
• reset()
• seek(progress)
• setSpeed(speed)
• setLoop(enabled)
• getTimeline()
• getAdapter()
• exportDiagram()

TypeScript types

The props interface and related types are exported for consumers that need them:

import type {
  DiagramPresenterProps,
  DiagramReadyPayload,
  DiagramPreset,
} from 'vitepress-theme-app-docs'

Example

<script setup lang="ts">
const flow = `flowchart TD
  Start([Start]) --> Input[/User Input/]
  Input --> Validate{Valid?}
  Validate -->|Yes| Process[Process Data]
  Validate -->|No| Error[Show Error]
  Error --> Input
  Process --> Done([Done])`
</script>

<VTDocDiagramPresenter
  :code="flow"
  preset="auto"
  auto-play="all"
  :highlight="['Process', 'Done']"
  highlight-mode="glow"
  caption="Animated validation flow"
/>

VTDocMermaidPlayground

VTDocMermaidPlayground renders a live configuration panel for VTDocDiagramPresenter. It is useful in internal preview sites and design reviews because it exposes diagram selection, feature presets, animation timing, captions, highlight settings, phase navigation, spotlight, and code snippet generation.

Usage:

<VTDocMermaidPlayground />

VTDocMindmapPlayground

VTDocMindmapPlayground provides an interactive sandbox for VTDocMindmap. It allows real-time editing of the Markdown hierarchy and tuning of Markmap options like expansion level and animation duration. For a full list of available settings, see the options reference.

Usage:

<VTDocMindmapPlayground />

Local preview site

This repository includes a VitePress site in docs/ that consumes the package theme from the local source tree. Use it to preview the package in a realistic environment.

pnpm docs:dev
pnpm docs:build
pnpm docs:preview

Quality checks

pnpm lint
pnpm typecheck
pnpm test:run

Commits also run Husky pre-commit, which executes lint-staged for staged *.ts and *.vue files.

Publishing to Nexus

The repository includes a .npmrc template with the expected settings:

1. Fill the scoped registry URL.
2. Set the auth token entry.
3. Publish with pnpm publish:nexus.

Before publishing, a safe packaging check is available:

pnpm publish:dry-run

Development notes

• files in package.json keeps the published tarball limited to the package sources — the preview site is excluded
• global-components.d.ts ships alongside index.ts for consumers who need to reference the augmentation explicitly
• tsconfig.json includes the preview site's VitePress TypeScript files so local wrappers stay type-checked
• Component source files use the VTDoc* prefix for consistency with the registered public names.