VitePress

VitePress is a documentation generator built on top of Vite and Vue 3, and it is the tool this course follows in detail. It belongs to a family of tools that all share the same promise — write Markdown, get a fast static website — but it makes a distinctive set of trade-offs. Where some documentation tools treat Vue, React, or Python as a required investment, VitePress treats them as optional: the generator is happy to produce a completely static site with no client-side framework at all, and the Vue runtime is only paid for on pages that actually contain interactive components. That decision shapes everything else about the tool, from how fast the dev server starts to how small the production bundle is.

What this chapter is for is practical rather than theoretical. The previous chapter established the general model — content in a repository, a build step, static output — and the goal here is to turn that model into a working site you could actually publish. You will set up a project, understand the configuration file and the options that matter in practice, learn the Markdown features that go beyond plain CommonMark, and finish by shipping the result to a real host. Each of those is a step in a workflow rather than a list of features to memorise, and the order matters: the configuration options in particular make much more sense once you have seen the project layout they apply to.

It is worth being honest about the trade-off you are making when you pick this tool over the others covered in the previous chapter. VitePress assumes you are willing to use Vite as your build system and, if you want interactivity, Vue 3 as your component model. In exchange you get a development experience that is unusually fast — the dev server starts almost instantly and updates individual pages without reloading the browser — a documentation theme that is genuinely well designed out of the box, and a build output that is small enough that performance rarely becomes a documentation problem. Teams that are already invested in the Vue ecosystem tend to find this an obvious choice; teams that are not should read the introduction and quick-start pages carefully before committing, because the ecosystem alignment is the main thing you are buying.

Nothing in this chapter assumes that you have used Vue. The framework’s own concepts are explained as they come up, and the only technical background you need is the same as for the previous chapter: Markdown, a terminal, and the general shape of a static site. The one place where it helps to have some Vue familiarity is if you intend to build custom components into your pages, and even then the examples provided are self-contained.

Chapters

Found an issue with this content?

Tell us what could be improved.