{"id":12642,"library":"vuepress","title":"VuePress 1.x Static Site Generator","description":"VuePress 1.x is a Vue-powered static site generator designed primarily for technical documentation. It enables authors to write content in Markdown and embed Vue components directly within it, offering a flexible and interactive documentation experience. The current stable version is 1.9.10, released in August 2023. Key differentiators include its Vue component-based layout system, a powerful plugin API for extending functionality, and a theming system. Since version 1.9.0, it features full TypeScript support for configuration files, and since 1.9.2, for plugins and themes, enhancing developer experience with type inference. While 1.x receives occasional bug fixes, it is officially in maintenance mode, with the core team's focus shifted to VuePress 2.x (which uses Vue 3 and ESM) and the even lighter-weight VitePress.","status":"maintenance","version":"1.9.10","language":"javascript","source_language":"en","source_url":"https://github.com/vuejs/vuepress","tags":["javascript","documentation","generator","vue"],"install":[{"cmd":"npm install vuepress","lang":"bash","label":"npm"},{"cmd":"yarn add vuepress","lang":"bash","label":"yarn"},{"cmd":"pnpm add vuepress","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Used in `.vuepress/config.ts` for type inference and helper functions. CommonJS `require` is not supported in VuePress 2.x and discouraged for new 1.x TypeScript configurations.","wrong":"const { defineConfig } = require('vuepress/config')","symbol":"defineConfig","correct":"import { defineConfig } from 'vuepress/config'"},{"note":"Specifically for providing type inference for custom theme configurations in `.vuepress/config.ts`.","symbol":"defineConfig4CustomTheme","correct":"import { defineConfig4CustomTheme } from 'vuepress/config'"},{"note":"A built-in component used directly in Markdown or Vue templates to ensure that its content is rendered only on the client side, preventing SSR mismatches for browser-specific components or libraries.","symbol":"ClientOnly","correct":""}],"quickstart":{"code":"{\n \"name\": \"my-docs\",\n \"version\": \"1.0.0\",\n \"description\": \"My awesome VuePress documentation\",\n \"main\": \"index.js\",\n \"scripts\": {\n \"docs:dev\": \"vuepress dev docs\",\n \"docs:build\": \"vuepress build docs\"\n },\n \"keywords\": [],\n \"author\": \"\",\n \"license\": \"MIT\",\n \"devDependencies\": {\n \"vuepress\": \"^1.9.10\",\n \"@vuepress/theme-default\": \"^1.9.10\"\n }\n}\n\n// docs/.vuepress/config.ts\nimport { defineConfig } from 'vuepress/config';\n\nexport default defineConfig({\n title: 'Hello VuePress 1.x',\n description: 'Just playing around',\n themeConfig: {\n nav: [\n { text: 'Home', link: '/' },\n { text: 'Guide', link: '/guide/' },\n { text: 'External', link: 'https://vuejs.org' }\n ],\n sidebar: [\n '/',\n '/guide/'\n ]\n }\n});\n\n// docs/README.md\n---\nlayout: home\n---\n\n# Hello VuePress!\n\nThis is my first VuePress 1.x site.\n\n\n

This paragraph only renders on the client side.

\n\n","lang":"typescript","description":"Demonstrates setting up a basic VuePress 1.x project, including package.json scripts, a TypeScript-based configuration file (`config.ts`) with navigation and sidebar, and a sample Markdown page using a built-in component."},"warnings":[{"fix":"For new projects, consider `npm init vuepress@next` for VuePress 2.x or `npm init vitepress` for VitePress. For existing 1.x projects, consult the VuePress 2.x migration guide for breaking changes in APIs, configuration, and plugin/theme compatibility.","message":"VuePress 1.x is in maintenance mode and not actively developed. VuePress 2.x (based on Vue 3 and pure ESM) introduces significant breaking changes and is not backward compatible. Users are encouraged to consider migrating to VuePress 2.x or VitePress for new projects or long-term maintenance.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Convert `module.exports = { ... }` to `import { defineConfig } from 'vuepress'; export default defineConfig({ ... })` and rename `.js` files to `.ts` or `.mjs`.","message":"VuePress 2.x removes support for CommonJS configuration files. All configurations (e.g., `.vuepress/config.js`) must be refactored to ESM (`.vuepress/config.ts` or `.vuepress/config.mjs`) when migrating.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Increase Node.js memory limit (e.g., `NODE_OPTIONS=--max_old_space_size=8192 vuepress build docs`). Consider optimizing the site structure, reducing the number of generated files, or migrating to VuePress 2.x, which uses Webpack 5/Vite and is generally more efficient.","message":"Large VuePress 1.x sites, especially with many pages or complex processing, can suffer from `FATAL ERROR: JavaScript heap out of memory` during the build process due to Webpack's memory consumption and VuePress 1.x's inefficiency with file handling.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure all custom components have names like `` or ``. If a component is expected to render differently on client/server or accesses browser-specific APIs, wrap it in `` component.","message":"Custom Vue components used directly in Markdown files must adhere to Vue's component naming conventions (PascalCase or contain a hyphen). Failure to do so can cause them to be treated as inline HTML elements and wrapped in `

` tags, leading to client-side hydration mismatches.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For Stylus, just write your `.styl` files. For other pre-processors (e.g., Sass, Less), refer to the VuePress advanced configuration guide to extend Webpack rules and install corresponding loaders (e.g., `sass-loader`, `node-sass`).","message":"VuePress 1.x uses Stylus internally, meaning you do not need to install `stylus` and `stylus-loader` for basic styling. However, for other CSS pre-processors, you must manually extend the internal Webpack config and install the necessary dependencies.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Increase Node.js memory allocation for the build command: `NODE_OPTIONS=--max_old_space_size=8192 yarn docs:build` (adjust size as needed, e.g., 4096, 12048).","cause":"VuePress 1.x build process consumes excessive memory, especially for large sites, leading to Node.js hitting its heap limit.","error":"FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory"},{"fix":"Replace non-standard HTML tags with modern, semantic HTML5 elements and CSS for styling. Use the `--debug` flag during development (`vuepress dev docs --debug`) to get warning logs about unrecognized tags.","cause":"Using non-standard or deprecated HTML tags (e.g., `

`, ``) in Markdown or Vue templates that Vue.js does not recognize as valid components or elements.","error":"[Vue warn]: Failed to resolve component: XXX"},{"fix":"Review your file structure and ensure each Markdown file has a unique URL path. Adjust directory structure or file names to avoid path conflicts. For example, use `a/b.md` OR `a/b/index.md`, but not both if they map to the same `/a/b/` URL.","cause":"Two or more Markdown files in the project resolve to the same URL path, causing one to overwrite the other during compilation. Common examples are `a/b.md` and `a/b/README.md`.","error":"warning Overriding existing page xxx"},{"fix":"If using CloudFlare, disable 'Auto Minify' for JavaScript and HTML. For components that behave differently, wrap them in VuePress's `` component. Set `__VUE_PROD_HYDRATION_MISMATCH_DETAILS__ = true` in development for detailed browser console errors.","cause":"Server-side rendered (SSR) HTML differs from the client-side rendered content. This can be caused by external services like CloudFlare's static resource compression, or Vue components rendering differently on the server vs. client.","error":"Hydration completed but contains mismatches"}],"ecosystem":"npm"}