vitepress-theme-app-docs

vitepress-theme-app-docs

🌎 English · 🇪🇸 Español

A VitePress theme for product and application documentation. It adds a custom visual layer, authoring components (callouts, cards, steps, tabs, accordions, FAQ, badges, file trees, columns, banners, framed images), Mermaid diagrams with animated walkthroughs (VTDocDiagramPresenter), interactive mindmaps (VTDocMindmap), print support, light/dark branding through design tokens, and English and Spanish UI strings with room for more languages.

Installation

pnpm add vitepress-theme-app-docs vitepress vue mermaid

vitepress, vue and mermaid are peer dependencies, so your site owns them. gsap, @heroicons/vue and vitepress-mermaid-renderer are regular dependencies and come with the package.

Requirements

• Node.js >=22 (22 and 24 are tested)
• VitePress ^1.6.4, Vue ^3.5.31, Mermaid ^11.14.0 || ^12.0.0
• TypeScript >=5.7, or "moduleResolution": "bundler" (the VitePress default), if you type-check your site
• pnpm (including the strict layout) and npm are tested

Quick start

1. Wrap your VitePress config. withAppDocs applies designTokens, generates the merged "All pages" document and registers the Vite plugin the theme needs.

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

export default withAppDocs(
  defineConfigWithTheme<ThemeConfig>({
    title: 'My product',
    themeConfig: {
      nav: [{ text: 'Guide', link: '/guide/' }],
      sidebar: [{ text: 'Guide', items: [{ text: 'Introduction', link: '/guide/' }] }],
    },
  }),
)

2. Use the theme.

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

export default Theme

To add your own components or hooks, extend it. Do not call the theme's enhanceApp yourself: VitePress already runs it.

import type { Theme } from 'vitepress'
import AppDocsTheme from 'vitepress-theme-app-docs'

export default {
  extends: AppDocsTheme,
  enhanceApp({ app }) {
    // register your own components here
  },
} satisfies Theme

3. Write Markdown. The components are registered globally, no imports needed:

---
title: Introduction
description: What this product does.
---

<VTDocTip>The page header above is built from the frontmatter.</VTDocTip>

<VTDocSteps>
  <VTDocStep title="Install">Add the package.</VTDocStep>
  <VTDocStep title="Write">Use the components.</VTDocStep>
</VTDocSteps>

Components

Registered globally by the theme and also exported by name from vitepress-theme-app-docs.

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

With withAppDocs, the presenter and the mindmap can also be written as code blocks, without a <script setup> or a code="…" attribute:

```mermaid presenter autoPlay=intersect caption="Order flow"
flowchart LR
  Order --> Pay --> Ship
```

```mindmap height=260px
# Plan
## Step
```

Plain ```mermaid code blocks are rendered too, through vitepress-mermaid-renderer, with a zoom/download/fullscreen toolbar. Mermaid is only downloaded by pages that have a diagram.

Configuration

Standard VitePress themeConfig fields all work. The theme adds:

designTokens and mergeDocs only work when the config is wrapped with withAppDocs.

TypeScript

The package ships generated declarations. Component props and related types (DiagramPresenterProps, DiagramPresenterExpose, VTDocMindmapProps, ThemeConfig, DesignTokens…) are exported from the root. To autocomplete the VTDoc* components in .vue files, add the GlobalComponents augmentation:

// tsconfig.json
{ "compilerOptions": { "types": ["vitepress-theme-app-docs/global-components"] } }

Customization

Brand colours and shapes come from designTokens, no CSS needed:

themeConfig: {
  designTokens: {
    brand: '#0ea5e9',
    radiusCard: '4px',
    dark: { brand: '#38bdf8' },
  },
}

Callouts also expose CSS custom properties of the form --vtd-c-{type}-{role} (type: note, tip, warning, info, check; role: bg, border, text, icon) that you can override in your own CSS. The default brand colour is violet; set designTokens.brand to change it.

Language flags

Turn the flags on with themeConfig.languageFlags: true. English (GB) and Spanish (ES) are built in; a language without a flag keeps VitePress's globe icon. To add another language (French here), wire two CSS variables:

/* the navbar button while French is active */
html[lang^='fr'] { --vt-current-flag: url('/path-to-fr-flag.svg'); }

/* the French entry in the language menu */
[href*='/fr/'] { --vt-item-flag: url('/path-to-fr-flag.svg'); }

The same variables override the built-in flags.

Documentation

The guides live in docs/guide/ (and docs/es/guide/ in Spanish) in the repository; pnpm docs:dev serves them as a site.

• Getting started: install, wrap the theme, TypeScript, package managers
• Components, Mermaid Diagrams, Mindmaps, Playground
• Customization (tokens, CSS variables), Customizing the layout (slots), Internationalization, Accessibility
• Merging Docs: the "All pages" document
• Authoring Rules: how to write Markdown that renders correctly with the components
• Public API and versioning, Troubleshooting

Upgrading from 0.9? Read MIGRATION.md. Release notes are in CHANGELOG.md. Both ship in the package.

Public API and support

The public API, the semantic-versioning policy and the support matrix (VitePress 1.6, Vue 3.5, Node 22 and 24, TypeScript 5.7) are defined in the Public API and versioning guide. Diagram adapters are an internal API.

Contributing

Development setup, the quality gates and the publishing workflow are in CONTRIBUTING.md; coding-agent guidance is in AGENTS.md (both in the repository).

License

MIT