{"id":14247,"library":"vitepress","title":"VitePress","description":"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.","status":"active","version":"1.6.4","language":"javascript","source_language":"en","source_url":"https://github.com/vuejs/vitepress","tags":["javascript","vite","vue","vitepress","typescript"],"install":[{"cmd":"npm install vitepress","lang":"bash","label":"npm"},{"cmd":"yarn add vitepress","lang":"bash","label":"yarn"},{"cmd":"pnpm add vitepress","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for advanced CSS processing, especially for style isolation or custom PostCSS plugins.","package":"postcss","optional":false},{"reason":"Peer dependency for rendering MathJax equations in Markdown. Only needed if mathematical expressions are used.","package":"markdown-it-mathjax3","optional":true}],"imports":[{"note":"Used in `.vitepress/config.ts` for type-safe configuration. VitePress config files should be ESM.","wrong":"const defineConfig = require('vitepress')","symbol":"defineConfig","correct":"import { defineConfig } from 'vitepress'"},{"note":"A Vue Composition API composable for accessing page-specific and site-wide data in theme components.","symbol":"useData","correct":"import { useData } from 'vitepress'"},{"note":"A helper function to prepend the site's `base` path to a URL, essential for handling assets and links correctly, especially when deploying to a sub-directory.","symbol":"withBase","correct":"import { withBase } from 'vitepress'"},{"note":"Used when extending the default theme in a custom theme entry file (`.vitepress/theme/index.ts`).","symbol":"DefaultTheme","correct":"import DefaultTheme from 'vitepress/theme'"}],"quickstart":{"code":"{\n  \"name\": \"my-docs\",\n  \"type\": \"module\",\n  \"scripts\": {\n    \"docs:dev\": \"vitepress dev docs\",\n    \"docs:build\": \"vitepress build docs\",\n    \"docs:preview\": \"vitepress preview docs\"\n  },\n  \"devDependencies\": {\n    \"vitepress\": \"^1.0.0-rc.x\",\n    \"vue\": \"^3.4.0\"\n  }\n}\n\n// .vitepress/config.ts\nimport { defineConfig } from 'vitepress'\n\nexport default defineConfig({\n  title: 'My Awesome Docs',\n  description: 'A VitePress Site',\n  base: process.env.VITEPRESS_BASE ?? '/',\n  themeConfig: {\n    nav: [\n      { text: 'Home', link: '/' },\n      { text: 'Guide', link: '/guide/' }\n    ],\n    sidebar: [\n      {\n        text: 'Guide',\n        items: [\n          { text: 'Introduction', link: '/guide/introduction' },\n          { text: 'Getting Started', link: '/guide/getting-started' }\n        ]\n      }\n    ],\n    // Add social links if needed\n    // socialLinks: [\n    //   { icon: 'github', link: 'https://github.com/vuejs/vitepress' }\n    // ],\n    footer: {\n      message: 'Released under the MIT License.',\n      copyright: 'Copyright © 2024-present John Doe'\n    }\n  }\n})\n\n<!-- docs/index.md -->\n---\nlayout: home\nhero:\n  name: \"My Awesome Project\"\n  text: \"A VitePress site example.\"\n  tagline: My great project tagline\n  actions:\n    - theme: brand\n      text: Get Started\n      link: /guide/getting-started\n    - theme: alt\n      text: View on GitHub\n      link: https://github.com/your-org/your-repo\n---\n\n## Welcome\n\nThis is the homepage of my VitePress documentation site. Explore the navigation and sidebar to learn more.","lang":"typescript","description":"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."},"warnings":[{"fix":"Refer to the official VitePress migration guide from 0.x to 1.x and update your configuration and theme files accordingly.","message":"Migrating from VitePress 0.x to 1.x involves significant breaking changes. Key changes include a restructured `sidebar` option (children key renamed to `items`), `home: true` in frontmatter becoming `layout: home`, and removal of `repo`, `editLinks` from theme config in favor of more flexible APIs.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"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.","message":"VitePress 2.x (currently in alpha) introduces further architectural changes. Configurations are ESM-only, and Vue 3 compatibility is enforced. The theme API is redesigned, making v1.x themes incompatible.","severity":"breaking","affected_versions":">=2.0.0-alpha"},{"fix":"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`.","message":"Environment variables (`process.env.VITE_APP_KEY`) are not directly accessible in the VitePress configuration file (`.vitepress/config.ts`) during build. The config file is evaluated server-side, not client-side.","severity":"gotcha","affected_versions":">=0.x"},{"fix":"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.","message":"Components embedded directly in Markdown files or custom themes must be SSR-compatible due to VitePress's static build process. Direct access to browser-specific APIs (e.g., `window`, `document`) will cause errors during build.","severity":"gotcha","affected_versions":">=0.x"},{"fix":"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\"])`).","message":"Applying custom global styles may require specific PostCSS configuration to ensure proper style isolation and prevent conflicts, especially with VitePress's default theme styles or when dealing with RTL (right-to-left) layouts.","severity":"gotcha","affected_versions":">=0.x"}],"env_vars":null,"search_vec":"'1.6.4':54 '2':61 'activ':56 'addit':162 'allow':85 'alpha':68,150 'approach':84 'architectur':74 'asset':108 'blog':22 'branch':147 'bring':72 'cadenc':138 'capabl':96 'centric':26 'compon':90 'content':25 'content-centr':24 'continu':158 'creat':19 'critic':130 'current':50,66 'design':17 'develop':35,57 'direct':86 'distinguish':77 'document':20,117 'embed':87 'enhanc':75 'except':34 'expect':70 'experi':36 'extrem':102 'fast':44,103 'featur':161 'file':93 'first':83 'focus':99 'foundat':113 'frequent':149 'friend':106 'generat':9,101 'high':5 'highlight':124 'hmr':48 'hot':45 'improv':159 'instant':38 'iter':156 'javascript':163 'leverag':30 'lightn':43 'lightning-fast':42 'maintain':134 'major':155 'markdown':82,92 'markdown-first':81 'minor':140 'modul':46 'next':154 'offer':37 'offici':116 'patch':142 'perform':6,128 'power':11 'primarili':16 'progress':58 'project':131,133 'reflect':157 'regular':136 'releas':63,137 'reload':47 'robust':94 'rollup':120 'seo':105 'seo-friend':104 'serv':110 'server':39 'signific':73 'site':8,28 'ssg':10 'stabil':126 'stabl':51,146 'start':40 'static':7,27,107 'theme':95 'toward':59 'typescript':167 'updat':151 'version':52,143 'vite':13,31,119,164 'vitepress':1,2,76,166 'vue':89,122,165 'vue.js':15 'websit':21 'within':91 'x':62","created_at":"2026-04-20T01:58:41.719441+00:00","updated_at":"2026-04-20T01:58:41.719441+00:00","problems":[{"fix":"Rename your config file to `.vitepress/config.mjs` or `.vitepress/config.ts` and rewrite the export statement to `export default defineConfig({...})`.","cause":"The VitePress configuration file is written in CommonJS syntax (`module.exports = {}`) but VitePress expects an ES Module (`export default {}`).","error":"ERR_REQUIRE_ESM: require() of ES Module ...vitepress/config.js not supported"},{"fix":"Ensure `vitepress` is correctly installed. If extending the default theme, use `import DefaultTheme from 'vitepress/theme'` in your `.vitepress/theme/index.ts` file.","cause":"The theme entry file is trying to import `vitepress/theme` but the path is incorrect or the default theme cannot be found.","error":"Error: Failed to resolve import \"vitepress/theme\" from \"/.vitepress/theme/index.ts\""},{"fix":"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).","cause":"Accessing `process.env` directly in client-side code or SSR-rendered components without proper Vite configuration for environment variables.","error":"ReferenceError: process is not defined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"vitepress","cli_version":null,"type":"library","homepage":"https://vitepress.dev","github":"https://github.com/vuejs/vitepress","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/vitepress","openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework","serialization","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}