VuePress Theme for Official Vue Projects (v1)

1.1.1 · maintenance · verified Sun Apr 19

The `@vuepress/theme-vue` package provides the official theme for VuePress 1.x, a minimalistic Vue-powered static site generator. Currently in maintenance mode, with its last major update (1.9.10) published approximately two years ago, this theme is built on Vue 2 and Webpack, inheriting the core architecture of VuePress v1. It focuses on delivering a robust, opinionated base for documentation sites, offering sensible defaults for navigation bars, sidebars, homepage layouts, and search functionalities. While VuePress v2 (based on Vue 3 and Vite/Webpack) offers a re-designed API and different theme system, this package remains the standard for projects specifically using VuePress v1. Its key differentiators include official backing for VuePress v1 and a highly customizable structure through `themeConfig` and custom styles, making it suitable for stable, established documentation projects that do not require migration to VuePress v2. Community-driven alternatives like `vuepress-theme-hope` typically target VuePress v2.

Common errors

```
Error: Cannot find module '@vuepress/theme-vue'
```
cause The `@vuepress/theme-vue` package is either not installed, or there's a typo in the `theme` configuration string in `.vuepress/config.js`.

fix Ensure the package is installed via `npm install @vuepress/theme-vue` or `yarn add @vuepress/theme-vue`, and verify the `theme: '@vuepress/theme-vue'` setting in your `.vuepress/config.js` is correct.
```
404 Not Found (for pages with non-standard URL characters)
```
cause VuePress v1, and some themes, can have issues with URLs generated from frontmatter (like categories or tags) containing non-standard characters (e.g., Chinese characters, spaces, special symbols) due to `vue-router`'s handling of encoded paths.

fix Avoid using non-URL-friendly characters in frontmatter fields that generate URLs (like `category` or `tags`). Use URL-safe alternatives or slugs. If using `vue-router` versions beyond 3.4.5, consider downgrading or applying a `resolutions` field in `package.json` to lock `vue-router` to `3.4.5` if applicable.
```
warning Overriding existing page xxx
```
cause This warning indicates that two or more Markdown files are being resolved to the same URL path, causing one page's content to be overwritten. This often happens due to conflicting file structures or `permalink` configurations.

fix Review your file structure and `permalink` settings in page frontmatter to ensure each page resolves to a unique path. Use the `--debug` flag with `vuepress dev` to get more detailed path resolution information.

Warnings

breaking This theme is designed exclusively for VuePress v1, which is built on Vue 2. Migrating to VuePress v2 requires a complete rewrite, as v2 is based on Vue 3, uses ESM, and has a re-designed API with significant breaking changes in theme development and configuration structure.
Fix: For new projects, consider VuePress v2 or VitePress. For existing v1 projects, consult the 'Migrating from v1' guide in the VuePress v2 documentation for a comprehensive list of changes.
deprecated VuePress v1, and consequently this theme, is in maintenance mode. This means no new features will be added, and only critical bug fixes are provided.
Fix: New projects requiring active development, modern features, or Vue 3 support should consider VuePress v2 or VitePress. Existing v1 projects should factor in the lack of future feature enhancements.
gotcha Customizing the theme by 'ejecting' its source code (`vuepress eject`) is a one-way operation. Once ejected, your custom theme will no longer receive updates or bug fixes from the official `@vuepress/theme-vue` package, even if you upgrade VuePress.
Fix: For minor customizations, leverage `themeConfig` options or override styles via `.vuepress/styles/index.styl` and `palette.styl`. Only eject if extensive, deep customization is absolutely necessary and you are prepared to maintain the entire theme codebase.
gotcha VuePress v1 config files (`.vuepress/config.js`) must be CommonJS modules, not ES Modules. Attempting to use `import`/`export` syntax directly in `config.js` will result in errors.
Fix: Ensure that `.vuepress/config.js` uses `module.exports = { ... }` syntax for configuration. For VuePress v2, config files support TypeScript and ESM.

Install

npm install vuepress-theme-vue npm
yarn add vuepress-theme-vue yarn
pnpm add vuepress-theme-vue pnpm

Imports

theme configuration string
wrong:
```
import { themeVue } from '@vuepress/theme-vue';
```
correct:
```
// .vuepress/config.js
module.exports = {
  theme: '@vuepress/theme-vue',
  themeConfig: {
    // Theme-specific options
  }
}
```
For VuePress v1, themes are primarily configured via a string name in `.vuepress/config.js` (CommonJS), not directly imported into application code.

theme object direct import (advanced)

wrong:

import themeVue from '@vuepress/theme-vue'; // ESM not supported in VuePress v1 config

correct:

// .vuepress/config.js
const themeVue = require('@vuepress/theme-vue');

module.exports = {
  theme: themeVue,
  themeConfig: {
    // Theme-specific options
  }
}

While possible to import the theme object directly, it's less common for official themes which VuePress resolves by name. VuePress v1 config files are CommonJS.

$site.themeConfig (accessing theme options in Vue components)

wrong:

import { themeConfig } from '@vuepress/theme-vue'; // Not how runtime config is accessed

correct:

<template>
  <div>
    <h1>{{ $site.title }}</h1>
    <p>Theme color: {{ $site.themeConfig.accentColor || 'default' }}</p>
    <Content />
  </div>
</template>

Theme-specific options configured in `themeConfig` are exposed globally via the `$site.themeConfig` object within Vue components in VuePress v1.

Quickstart

This quickstart sets up a basic VuePress v1 project with the `@vuepress/theme-vue` configured. It includes a `README.md` for the homepage, a 'guide' page, and a `.vuepress/config.js` with basic theme options, showing how to structure a VuePress v1 site to utilize this theme.

mkdir my-docs
cd my-docs

npm init -y
npm install -D vuepress @vuepress/theme-vue

mkdir .vuepress

cat > .vuepress/config.js << EOF
module.exports = {
  title: 'My VuePress v1 Site',
  description: 'A simple documentation site using the official VuePress v1 theme.',
  theme: '@vuepress/theme-vue',
  themeConfig: {
    navbar: [
      { text: 'Home', link: '/' },
      { text: 'Guide', link: '/guide/' }
    ],
    sidebar: [
      '/',
      '/guide/'
    ],
    lastUpdated: 'Last Updated',
    repo: 'vuejs/vuepress' // Example GitHub repo link
  }
}
EOF

cat > README.md << EOF
---
home: true
heroText: Hello VuePress v1
tagline: The official theme for your docs
features:
- title: Simplicity First
  details: Minimal setup helps you focus on writing.
- title: Vue-Powered
  details: Enjoy the dev experience of Vue + webpack.
- title: Performant
  details: Generates pre-rendered static HTML.
footer: MIT Licensed | Copyright © 2018-present My Name
---

# Welcome to My Docs

This is your home page content.
EOF

mkdir guide
cat > guide/README.md << EOF
# Guide

This is your guide page.

## Section One

Content for section one.

## Section Two

Content for section two.
EOF

cat > package.json << EOF
{
  "name": "my-docs",
  "version": "1.0.0",
  "main": "index.js",
  "scripts": {
    "docs:dev": "vuepress dev",
    "docs:build": "vuepress build"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "vuepress": "^1.9.10",
    "@vuepress/theme-vue": "^1.9.10"
  }
}
EOF

npm run docs:dev

view raw JSON →