Registry / web-framework / vuepress-theme-vue

vuepress-theme-vue

library1.1.1jsnpmunverified

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.

web-framework

npm install vuepress-theme-vue

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VUEPRESS-THEME-VUE

vuepress-theme-vue

web-frameworkjavascriptv1.1.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

theme configuration string

✓ // .vuepress/config.js module.exports = { theme: '@vuepress/theme-vue', themeConfig: { // Theme-specific options } }

✗ import { themeVue } from '@vuepress/theme-vue';

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)

✓ // .vuepress/config.js const themeVue = require('@vuepress/theme-vue'); module.exports = { theme: themeVue, themeConfig: { // Theme-specific options } }

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

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)

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

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

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

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

Debug

Known issues

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

affects: >=1.0.0

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

affects: >=1.0.0

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

affects: >=1.0.0

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

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module '@vuepress/theme-vue'

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)

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

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.

Upgrade

Version history

1.1.1latest on npm

Audit

Dependencies

vuepressrequiredRuntime dependency for VuePress v1 core functionality. This theme is designed to run exclusively within a VuePress v1 environment.

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/vuejs/vuepress-theme-vue ↗

packagehttps://www.npmjs.com/package/vuepress-theme-vue ↗

homepagehttps://v1.vuepress.vuejs.org ↗