VitePress is a highly performant static site generator (SSG) powered by Vite and Vue.js, primarily designed for creating documentation websites, blogs, and content-centric static sites. It leverages Vite for an exceptional developer experience, offering instant server starts and lightning-fast hot module reloading (HMR). The current stable version is 1.6.4, with active development progressing towards a 2.x release, which is currently in alpha and expected to bring significant architectural enhancements. VitePress distinguishes itself through its markdown-first approach, allowing direct embedding of Vue components within Markdown files, robust theming capabilities, and a focus on generating extremely fast, SEO-friendly static assets. It serves as the foundation for the official documentation of Vite, Rollup, and Vue itself, highlighting its stability and performance for critical projects. The project maintains a regular release cadence for minor and patch versions on the stable branch, with frequent alpha updates for the next major iteration, reflecting continuous improvement and feature additions.
npm install vitepressVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates a minimal VitePress project setup with a `package.json`, basic site configuration (`.vitepress/config.ts`), and a homepage (`docs/index.md`). It includes scripts for development, build, and preview, and configures navigation, sidebar, and a hero section.
Refer to the official VitePress migration guide from 0.x to 1.x and update your configuration and theme files accordingly.
For new projects, start with the latest 2.x alpha. For existing v1.x projects, anticipate a significant migration effort, reviewing the v2 changelogs and documentation once a stable release is available.
Use Vite's `loadEnv` helper within your `defineConfig` export function to correctly load environment variables: `export default ({ mode }) => { const env = loadEnv(mode, process.cwd()); return defineConfig({ title: env.VITE_APP_TITLE }); }`. Alternatively, use a package like `dotenv`.Wrap non-SSR-friendly components or logic in the `<ClientOnly>` built-in component. Ensure browser-specific API calls are made within Vue's `onMounted` or `beforeMount` lifecycle hooks.
Install `postcss` and configure `docs/postcss.config.mjs` to use `postcssIsolateStyles` from `vitepress`. For RTL, additional PostCSS plugins like `rtlcss` might be necessary, configured with specific prefixes (`:where([dir="ltr"])`, `:where([dir="rtl"])`).
Rename your config file to `.vitepress/config.mjs` or `.vitepress/config.ts` and rewrite the export statement to `export default defineConfig({...})`.Ensure `vitepress` is correctly installed. If extending the default theme, use `import DefaultTheme from 'vitepress/theme'` in your `.vitepress/theme/index.ts` file.
Prefix environment variables with `VITE_` (e.g., `VITE_MY_VAR`) and access them via `import.meta.env.VITE_MY_VAR` in client-side code. For server-side config files, use `loadEnv` (see Warnings section).