What does VitePress 1.6 do with a folder of Markdown files, and what does a minimal project need to build a documentation site?

juniormust knowfreq 30%

answer

Markdown becomes Vue components
static HTML first, then a SPA
a special dot folder
file path equals URL
dev, build, preview

basics

~20 s

VitePress compiles each Markdown file into a Vue component, prerenders every page to static HTML at build time, then hydrates it into a single-page app. A minimal project is Markdown pages plus .vitepress/config, run with vitepress dev and build.

solid answer

~40 s

VitePress is a static site generator built on Vite and Vue for documentation-style sites. Each .md file is compiled into a Vue single-file component; vitepress build renders every page to HTML in Node, so the first visit gets plain HTML, and the page then hydrates into a Vue app that handles later navigation without full reloads. A minimal project is a folder such as docs/ with an index.md and a .vitepress/config.mts that default-exports defineConfig({ title, description, themeConfig }). Routes follow file paths: guide/installation.md becomes /guide/installation.html. You run vitepress dev docs while writing, vitepress build docs to produce docs/.vitepress/dist, and vitepress preview docs to serve that output locally. The default theme supplies the nav bar, sidebar, local search and dark mode, configured through themeConfig.

VitePress is a static site generator built on Vite and Vue for documentation-style sites. Each `.md` file is compiled into a Vue single-file component; `vitepress build` renders every page to HTML in Node, so the first visit gets plain HTML, and the page then hydrates into a Vue app that handles later navigation without full reloads. A minimal project is a folder such as `docs/` with an `index.md` and a `.vitepress/config.mts` that default-exports `defineConfig({ title, description, themeConfig })`. Routes follow file paths: `guide/installation.md` becomes `/guide/installation.html`. You run `vitepress dev docs` while writing, `vitepress build docs` to produce `docs/.vitepress/dist`, and `vitepress preview docs` to serve that output locally. The default theme supplies the nav bar, sidebar, local search and dark mode, configured through `themeConfig`.

code

bash · 4 lines

bash

npm add -D vitepress
npx vitepress dev docs      # write with hot updates
npx vitepress build docs    # prerender to docs/.vitepress/dist
npx vitepress preview docs  # serve the build on localhost:4173

go deeper

for a junior

Recall that VitePress turns Markdown into a prerendered static site, that config lives in .vitepress/config, and the dev, build and preview commands.

for a middle

Explain Markdown-to-Vue compilation, prerender then hydrate, file-based routing and where the build output goes.

for a senior

Show when VitePress fits a docs site and what the static model rules out, such as request-time logic and browser-only code during the build.

for a principal

Weigh owning a VitePress docs site in the library repo against other publishing setups: release coupling, contributor workflow and hosting constraints.

What VitePress is for

VitePress is a static site generator built on Vite and Vue, aimed at content-heavy sites such as the documentation of a Vue component library. You write Markdown; VitePress applies a theme and produces static HTML files that any static file host can serve.

What sets it apart from a plain Markdown-to-HTML tool is how the page works in the browser:

Each Markdown page becomes a Vue component. VitePress compiles the Markdown to HTML and then treats the result as a Vue single-file component, so pages can use Vue syntax and components.
The build prerenders every page. vitepress build renders each page to HTML in Node, so the first visit is fast and indexable.
The page then hydrates into a single-page app. Later navigation fetches the next page's chunk and swaps content without a full reload, and links in the viewport are prefetched.
Static parts are cheap. Vue's compiler separates static from dynamic content, so the purely static parts of a page are left out of the initial JavaScript payload and skipped during hydration.

A minimal project

For a UI library repository, the docs usually live in a docs/ folder:

Path	Purpose
`docs/index.md`	the home page, served at `/`
`docs/guide/installation.md`	served at `/guide/installation.html`
`docs/.vitepress/config.mts`	site config: title, description, theme config
`docs/.vitepress/theme/`	optional theme customisation
`docs/public/`	files copied as-is, such as a logo

The .vitepress directory is reserved: it holds the config, the dev cache (.vitepress/cache), the default build output (.vitepress/dist) and any theme code. The config file may be config.js, config.ts, config.mjs or config.mts.

// docs/.vitepress/config.mts
import { defineConfig } from 'vitepress'

export default defineConfig({
  title: 'Nimbus UI',
  description: 'Accessible Vue 3 components',
  themeConfig: {
    nav: [{ text: 'Guide', link: '/guide/installation' }],
    sidebar: [{ text: 'Components', items: [{ text: 'Button', link: '/components/button' }] }],
    search: { provider: 'local' },
  },
})

The three commands

vitepress dev docs starts the Vite dev server with hot updates. It renders pages in the browser only.
vitepress build docs prerenders every page and writes docs/.vitepress/dist.
vitepress preview docs serves that output locally, on port 4173 by default, so you can test the real build.

vitepress init scaffolds the folder and config through a few prompts.

File-based routing

The URL mirrors the file path relative to the source directory, which is the project root unless srcDir says otherwise:

index.md becomes /index.html, reachable as /;
guide/index.md becomes /guide/index.html, reachable as /guide/;
components/button.md becomes /components/button.html.

By default links and files keep the .html extension; the cleanUrls option removes it from links when the host can serve extensionless URLs.

What the default theme adds

Without writing any Vue, the default theme gives you a nav bar, a sidebar, an on-page outline, previous and next links, a dark-mode toggle (appearance is on by default) and, with search: { provider: 'local' }, in-browser full-text search. All of it is driven by themeConfig in the site config and by per-page frontmatter.

Where it stops

VitePress builds a static site: there is no server at request time. Anything dynamic runs in the browser after hydration, and every page and component must render in Node during the build.

Why a component library picks it

For the docs of an open-source Vue UI library, VitePress fits for concrete reasons:

Demos are real Vue. A page can import the library's components and render them live, with no separate playground build.
One toolchain. The docs run on Vite, like the library itself, so aliases, TypeScript and single-file components behave the same way.
Docs next to code. The docs/ folder sits in the library repository, so a pull request can change a component and its page together.
Static output. The result is a folder of files that any static host can serve, with no server to operate.

What it does not give you is request-time behaviour. The built-in local search runs in the browser against an index made at build time, and anything personalised happens client-side after hydration.

Minimal workflow from zero

Install vitepress as a dev dependency.
Run npx vitepress init and choose ./docs as the root.
Write docs/index.md and a first guide page.
Run vitepress dev docs while writing, and vitepress build docs in CI.

## What VitePress is for VitePress is a **static site generator** built on Vite and Vue, aimed at content-heavy sites such as the documentation of a Vue component library. You write Markdown; VitePress applies a theme and produces static HTML files that any static file host can serve. What sets it apart from a plain Markdown-to-HTML tool is how the page works in the browser: 1. **Each Markdown page becomes a Vue component.** VitePress compiles the Markdown to HTML and then treats the result as a Vue single-file component, so pages can use Vue syntax and components. 2. **The build prerenders every page.** `vitepress build` renders each page to HTML in Node, so the first visit is fast and indexable. 3. **The page then hydrates into a single-page app.** Later navigation fetches the next page's chunk and swaps content without a full reload, and links in the viewport are prefetched. 4. **Static parts are cheap.** Vue's compiler separates static from dynamic content, so the purely static parts of a page are left out of the initial JavaScript payload and skipped during hydration. ## A minimal project For a UI library repository, the docs usually live in a `docs/` folder: | Path | Purpose | |---|---| | `docs/index.md` | the home page, served at `/` | | `docs/guide/installation.md` | served at `/guide/installation.html` | | `docs/.vitepress/config.mts` | site config: title, description, theme config | | `docs/.vitepress/theme/` | optional theme customisation | | `docs/public/` | files copied as-is, such as a logo | The `.vitepress` directory is reserved: it holds the config, the dev cache (`.vitepress/cache`), the default build output (`.vitepress/dist`) and any theme code. The config file may be `config.js`, `config.ts`, `config.mjs` or `config.mts`. ```ts // docs/.vitepress/config.mts import { defineConfig } from 'vitepress' export default defineConfig({ title: 'Nimbus UI', description: 'Accessible Vue 3 components', themeConfig: { nav: [{ text: 'Guide', link: '/guide/installation' }], sidebar: [{ text: 'Components', items: [{ text: 'Button', link: '/components/button' }] }], search: { provider: 'local' }, }, }) ``` ## The three commands - `vitepress dev docs` starts the Vite dev server with hot updates. It renders pages in the browser only. - `vitepress build docs` prerenders every page and writes `docs/.vitepress/dist`. - `vitepress preview docs` serves that output locally, on port 4173 by default, so you can test the real build. `vitepress init` scaffolds the folder and config through a few prompts. ## File-based routing The URL mirrors the file path relative to the source directory, which is the project root unless `srcDir` says otherwise: - `index.md` becomes `/index.html`, reachable as `/`; - `guide/index.md` becomes `/guide/index.html`, reachable as `/guide/`; - `components/button.md` becomes `/components/button.html`. By default links and files keep the `.html` extension; the `cleanUrls` option removes it from links when the host can serve extensionless URLs. ## What the default theme adds Without writing any Vue, the default theme gives you a nav bar, a sidebar, an on-page outline, previous and next links, a dark-mode toggle (`appearance` is on by default) and, with `search: { provider: 'local' }`, in-browser full-text search. All of it is driven by `themeConfig` in the site config and by per-page frontmatter. ## Where it stops VitePress builds a static site: there is no server at request time. Anything dynamic runs in the browser after hydration, and every page and component must render in Node during the build. ## Why a component library picks it For the docs of an open-source Vue UI library, VitePress fits for concrete reasons: - **Demos are real Vue.** A page can import the library's components and render them live, with no separate playground build. - **One toolchain.** The docs run on Vite, like the library itself, so aliases, TypeScript and single-file components behave the same way. - **Docs next to code.** The `docs/` folder sits in the library repository, so a pull request can change a component and its page together. - **Static output.** The result is a folder of files that any static host can serve, with no server to operate. What it does not give you is request-time behaviour. The built-in local search runs in the browser against an index made at build time, and anything personalised happens client-side after hydration. ## Minimal workflow from zero 1. Install `vitepress` as a dev dependency. 2. Run `npx vitepress init` and choose `./docs` as the root. 3. Write `docs/index.md` and a first guide page. 4. Run `vitepress dev docs` while writing, and `vitepress build docs` in CI.

Why is a VitePress site fast on first load even though every page is a Vue component?
The build prerenders each page to HTML, so the first response is ready to display. Vue's compiler also separates static Markdown from dynamic parts; static content is left out of the initial JavaScript payload and skipped during hydration, so a mostly-text page ships little script.
What is the difference between the project root and srcDir in VitePress?
The project root is where VitePress looks for the `.vitepress` folder, set by the directory you pass to the CLI. `srcDir` is where the Markdown pages live and defaults to the project root. Setting `srcDir: './src'` moves the pages without moving `.vitepress`, and URLs are then computed relative to `srcDir`.

saying these in an interview costs you the question

VitePress renders every page on a server at request time.
Each page navigation in a VitePress site is a full page reload.
The VitePress config file lives at the project root as vitepress.config.ts.
The default build output goes to a dist folder next to package.json.
Using Vue components in pages requires a separate plugin.

What does VitePress 1.6 do with a folder of Markdown files, and what does a minimal project need to build a documentation site?

§ answer

basics

solid answer

code

§ go deeper

▾level notes4 levels

▾deep dive~4 min

What VitePress is for

A minimal project

The three commands

File-based routing

What the default theme adds

Where it stops

Why a component library picks it

Minimal workflow from zero

▾common follow-ups2 questions

▾red flags5 flags

What VitePress is for

A minimal project

The three commands

File-based routing

What the default theme adds

Where it stops

Why a component library picks it

Minimal workflow from zero

answer

go deeper