English for VitePress Developers
Vocabulary for developers building documentation sites with VitePress — Vue-powered SSG, the default theme, config-driven navigation, and Vite-based dev server talk for English-speaking teams.
VitePress is a Vue-powered static site generator focused on documentation, built on top of Vite for a fast local dev server and build pipeline. It’s become a popular choice for open-source project docs (including Vite’s own site and Vue’s), and its vocabulary blends Vite/Vue terms with documentation-site concepts like “default theme” and “frontmatter-driven config.” This guide covers the terms you’ll need.
Core Architecture
Vite-powered dev server — VitePress inherits Vite’s fast, on-demand compilation, so the local preview updates almost instantly when you edit a markdown file. “We’re used to waiting several seconds for a docs preview to rebuild elsewhere — with VitePress’s Vite-powered dev server, edits show up almost instantly.”
Default theme — VitePress ships a polished, ready-to-use documentation theme out of the box, configurable through simple config options rather than requiring you to build a layout from scratch.
“We didn’t build a custom theme at all — the default theme covered everything we needed, just configured through
config.mts.”
Custom theme — for teams that need a fully bespoke design, VitePress supports replacing the default theme entirely with your own Vue components.
“Once our brand guidelines required a very specific layout, we moved from the default theme to a custom theme built from our own Vue components.”
Configuration
config.mts
The config.mts (or .js) file is the central configuration for the site — title, navigation, sidebar structure, and theme options all live here.
“Adding a new top-level nav item is one line in
config.mts— no separate routing file to touch.”
Sidebar Config
The sidebar config defines the navigation tree shown alongside content, either as a single global sidebar or scoped per top-level section.
“We scoped the sidebar per section, so the ‘Guide’ and ‘API Reference’ sections each show their own relevant navigation instead of one long combined list.”
Frontmatter-Driven Config
Many page-level settings — like disabling the sidebar for a specific page, or setting a custom layout — are controlled through frontmatter, rather than a separate routing config.
“We disabled the sidebar on the landing page just by setting
layout: homein its frontmatter — no code change needed.”
Markdown Extensions
Custom containers — VitePress-specific markdown syntax (like ::: tip or ::: warning) for rendering styled callout boxes without writing raw HTML.
“We wrapped the migration warning in a
::: warningcontainer so it stands out visually from the surrounding prose.”
Code group — a markdown extension letting you show the same example in multiple languages or package managers as tabs (like npm, yarn, pnpm) within one code block.
“Instead of three separate code blocks for npm, yarn, and pnpm, we use a code group — readers just click the tab for their package manager.”
Line highlighting — markdown syntax for highlighting specific lines within a code block, useful for drawing attention to the exact line being discussed in the surrounding prose.
“We highlighted line 4 in the snippet because that’s the line the following paragraph explains in detail.”
Vue Integration
Vue components in markdown — because VitePress is Vue-powered, you can import and use Vue components directly inside markdown files, similar to MDX in the React ecosystem.
“We embedded a live, interactive Vue component directly in the docs page so readers can try the API without leaving the documentation.”
Composable — a reusable piece of stateful logic (a Vue Composition API concept) that a custom theme or embedded component can use, shared across multiple pages.
“We wrote a small composable to track the reader’s selected package manager preference, so the code group tabs stay in sync across the whole site.”
Build and Deployment
Static build output — VitePress produces a fully static HTML/JS/CSS bundle at build time, deployable to any static host without a Node.js server at runtime.
“There’s no server to run in production — the build output is static files we can deploy straight to any CDN.”
Dead link checking — VitePress can be configured to fail the build if internal markdown links point to pages that don’t exist, catching broken references before deploy.
“We enabled dead link checking in CI, so a typo’d internal link now fails the build instead of quietly shipping a 404.”
Explaining VitePress to a Team
| Situation | Phrase |
|---|---|
| Justifying the choice for a Vue-ecosystem project | ”Since our team already writes Vue daily, extending the theme with our own components felt natural — there’s no separate templating language to learn.” |
| Explaining a config change | ”Adding the new section to the sidebar is a config change, not a code change — anyone comfortable editing JSON-like config can do it.” |
| Describing dead link checking | ”The build now fails on broken internal links deliberately — it’s meant to catch stale references before they reach production, not to block you unnecessarily.” |
| Discussing deployment | ”There’s no runtime server involved — we’re deploying the static build output straight to a CDN, same as any other static site.” |
Common Mistakes
- Calling VitePress “just markdown” — it supports embedding real Vue components in content, which is a meaningfully different capability than plain markdown.
- Saying “the sidebar is broken” when actually a page’s frontmatter overrides the global sidebar setting intentionally — check frontmatter before assuming a bug.
- Confusing a custom container (documentation-style callout syntax) with a custom theme (a full replacement of the site’s Vue components) — they solve very different problems.
Practice Exercise
- Explain, in two sentences, the difference between the default theme and a custom theme in VitePress.
- Write a short PR description for adding a code group to a documentation page that previously had separate code blocks per package manager.
- Draft a short explanation for a teammate of why dead link checking is enabled in CI and what to do when it fails a build.