VitePress

Last reviewed Aug 26, 2026 · 846 words

VitePress is a build step, not a service. You run it on your laptop or in CI, it emits a folder of static HTML in a few seconds, and the thing you actually self-host is a plain web server pointing at that folder. That distinction matters because people arrive at the 18,238-star repo expecting a wiki or a CMS with a login page, and what they get is the best documentation theme in the Node ecosystem plus a compiler. Set your expectations there and it is excellent.

It wins on the default theme, not on flexibility

The reason to pick VitePress over the dozen other static site generators is the theme you get for free: sidebar navigation generated from your folder structure, a local full-text search that ships in the build with no external service, a light and dark mode, an "edit this page" link to your repository, and code blocks with line highlighting and language tabs. For a project README that has outgrown one file, this is 90 percent of what you wanted and you have written zero CSS.

The flip side is that the default theme is docs-shaped. A blog is possible (the project's own site runs one) but you are working against the grain, and a marketing site is really not what this is for. If your site is not primarily reference material, Hugo or Astro are better tools, and I would rather see you in the blogging category looking at those than bending VitePress.

The whole setup is four commands

You need Node.js 18 or newer. From an empty folder:

npm add -D vitepress
npx vitepress init
npx vitepress dev
npx vitepress build

The init wizard writes a .vitepress/config.mts and a couple of sample pages. dev starts the Vite dev server on port 5173 with hot reload, which is where the "instant startup" claim comes from: Vite serves modules on demand rather than bundling first, so a 500-page site opens as fast as a 5-page one. build writes finished HTML into .vitepress/dist. That folder is the deliverable. Everything else in the repo is source.

Content is Markdown with a handful of extensions: custom containers (::: tip, ::: warning), frontmatter per page, and the ability to drop a Vue component into a page when a table or an interactive example needs it. That last part is where "Vue knowledge helps" in the catalogue is honest. You can go a long way with none, but the moment you want something the theme does not provide, the answer is a .vue file.

Serving it is a job for Caddy, not for Node

Because the output is static, there is no Node process running in production. On your server, a Caddy site block does the job:

docs.example.com {
    root * /srv/docs
    file_server
    try_files {path} {path}.html {path}/ =404
}

The try_files line matters. VitePress defaults to "clean URLs off", meaning links point at /guide/install.html. Set cleanUrls: true in the config and links become /guide/install, which then needs the web server to try the .html variant. The pattern above handles both. Behind Caddy with gzip and HTTP/2 the site scores near-perfect on every metric the static site performance guide cares about, because there is nothing to optimise: no database, no PHP, no runtime.

The tidy self-hosting loop is a Git push to your Gitea or Forgejo instance, a CI job that runs vitepress build, and an rsync of dist/ to the web root. That is the entire deployment pipeline and it runs in under a minute.

Where it loses to the alternatives

Against MkDocs with the Material theme: MkDocs is Python, its Material theme is arguably more configurable, and it does not need a JavaScript toolchain. If your team is Python-first, MkDocs will feel more native. Against Docusaurus: Docusaurus is React, heavier, slower to build, but has versioned docs and i18n as first-class features. VitePress has i18n; versioning you assemble yourself. Against Hugo: Hugo builds a 10,000-page site in seconds with a single binary and no Node, but its default themes are nowhere near as polished for documentation.

The other real cost is churn. VitePress lives on top of Vite and Vue, both of which move quickly, and a site left alone for a year will need npm update and a read of the changelog before it builds again. Static output never breaks, but the toolchain that produces it drifts.

What I'd do

For a project's documentation, a runbook collection, or an internal engineering handbook: VitePress, default theme, cleanUrls: true, built in CI and rsynced to a Caddy file server. Pin the VitePress version in package.json and bump it deliberately every few months rather than letting it float. For a personal blog or anything with a landing page, skip it and use Hugo or Astro. VitePress is a specialist, and it is very good at the one thing it specialises in.