VuePress 1.x Static Site Generator

Common errors

• FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory

  cause VuePress 1.x build process consumes excessive memory, especially for large sites, leading to Node.js hitting its heap limit.
  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).

• [Vue warn]: Failed to resolve component: XXX

  cause Using non-standard or deprecated HTML tags (e.g., `<center>`, `<font>`) in Markdown or Vue templates that Vue.js does not recognize as valid components or elements.
  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.

• warning Overriding existing page xxx

  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`.
  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.

• Hydration completed but contains mismatches

  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.
  fix If using CloudFlare, disable 'Auto Minify' for JavaScript and HTML. For components that behave differently, wrap them in VuePress's `<ClientOnly />` component. Set `__VUE_PROD_HYDRATION_MISMATCH_DETAILS__ = true` in development for detailed browser console errors.

Warnings

• breaking 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.
  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.
• breaking 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.
  Fix: Convert `module.exports = { ... }` to `import { defineConfig } from 'vuepress'; export default defineConfig({ ... })` and rename `.js` files to `.ts` or `.mjs`.
• gotcha 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.
  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.
• gotcha 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 `<p>` tags, leading to client-side hydration mismatches.
  Fix: Ensure all custom components have names like `<MyComponent>` or `<my-component>`. If a component is expected to render differently on client/server or accesses browser-specific APIs, wrap it in `<ClientOnly>` component.
• gotcha 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.
  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`).

Install

• npm install vuepress npm
• yarn add vuepress yarn
• pnpm add vuepress pnpm

Imports

• defineConfig
  wrong:

  const { defineConfig } = require('vuepress/config')

  correct:

  import { defineConfig } from 'vuepress/config'

  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.
• defineConfig4CustomTheme

  import { defineConfig4CustomTheme } from 'vuepress/config'

  Specifically for providing type inference for custom theme configurations in `.vuepress/config.ts`.
• ClientOnly

  <ClientOnly><NonSSRFriendlyComponent/></ClientOnly>

  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.

Quickstart

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.

{
  "name": "my-docs",
  "version": "1.0.0",
  "description": "My awesome VuePress documentation",
  "main": "index.js",
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  },
  "keywords": [],
  "author": "",
  "license": "MIT",
  "devDependencies": {
    "vuepress": "^1.9.10",
    "@vuepress/theme-default": "^1.9.10"
  }
}

// docs/.vuepress/config.ts
import { defineConfig } from 'vuepress/config';

export default defineConfig({
  title: 'Hello VuePress 1.x',
  description: 'Just playing around',
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Guide', link: '/guide/' },
      { text: 'External', link: 'https://vuejs.org' }
    ],
    sidebar: [
      '/',
      '/guide/'
    ]
  }
});

// docs/README.md
---
layout: home
---

# Hello VuePress!

This is my first VuePress 1.x site.

<ClientOnly>
  <p>This paragraph only renders on the client side.</p>
</ClientOnly>