{"id":12641,"library":"vuepress-theme-vue","title":"VuePress Theme for Official Vue Projects (v1)","description":"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.","status":"maintenance","version":"1.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/vuejs/vuepress-theme-vue","tags":["javascript","vue"],"install":[{"cmd":"npm install vuepress-theme-vue","lang":"bash","label":"npm"},{"cmd":"yarn add vuepress-theme-vue","lang":"bash","label":"yarn"},{"cmd":"pnpm add vuepress-theme-vue","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime dependency for VuePress v1 core functionality. This theme is designed to run exclusively within a VuePress v1 environment.","package":"vuepress","optional":false}],"imports":[{"note":"For VuePress v1, themes are primarily configured via a string name in `.vuepress/config.js` (CommonJS), not directly imported into application code.","wrong":"import { themeVue } from '@vuepress/theme-vue';","symbol":"theme configuration string","correct":"// .vuepress/config.js\nmodule.exports = {\n  theme: '@vuepress/theme-vue',\n  themeConfig: {\n    // Theme-specific options\n  }\n}"},{"note":"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.","wrong":"import themeVue from '@vuepress/theme-vue'; // ESM not supported in VuePress v1 config","symbol":"theme object direct import (advanced)","correct":"// .vuepress/config.js\nconst themeVue = require('@vuepress/theme-vue');\n\nmodule.exports = {\n  theme: themeVue,\n  themeConfig: {\n    // Theme-specific options\n  }\n}"},{"note":"Theme-specific options configured in `themeConfig` are exposed globally via the `$site.themeConfig` object within Vue components in VuePress v1.","wrong":"import { themeConfig } from '@vuepress/theme-vue'; // Not how runtime config is accessed","symbol":"$site.themeConfig (accessing theme options in Vue components)","correct":"<template>\n  <div>\n    <h1>{{ $site.title }}</h1>\n    <p>Theme color: {{ $site.themeConfig.accentColor || 'default' }}</p>\n    <Content />\n  </div>\n</template>"}],"quickstart":{"code":"mkdir my-docs\ncd my-docs\n\nnpm init -y\nnpm install -D vuepress @vuepress/theme-vue\n\nmkdir .vuepress\n\ncat > .vuepress/config.js << EOF\nmodule.exports = {\n  title: 'My VuePress v1 Site',\n  description: 'A simple documentation site using the official VuePress v1 theme.',\n  theme: '@vuepress/theme-vue',\n  themeConfig: {\n    navbar: [\n      { text: 'Home', link: '/' },\n      { text: 'Guide', link: '/guide/' }\n    ],\n    sidebar: [\n      '/',\n      '/guide/'\n    ],\n    lastUpdated: 'Last Updated',\n    repo: 'vuejs/vuepress' // Example GitHub repo link\n  }\n}\nEOF\n\ncat > README.md << EOF\n---\nhome: true\nheroText: Hello VuePress v1\ntagline: The official theme for your docs\nfeatures:\n- title: Simplicity First\n  details: Minimal setup helps you focus on writing.\n- title: Vue-Powered\n  details: Enjoy the dev experience of Vue + webpack.\n- title: Performant\n  details: Generates pre-rendered static HTML.\nfooter: MIT Licensed | Copyright © 2018-present My Name\n---\n\n# Welcome to My Docs\n\nThis is your home page content.\nEOF\n\nmkdir guide\ncat > guide/README.md << EOF\n# Guide\n\nThis is your guide page.\n\n## Section One\n\nContent for section one.\n\n## Section Two\n\nContent for section two.\nEOF\n\ncat > package.json << EOF\n{\n  \"name\": \"my-docs\",\n  \"version\": \"1.0.0\",\n  \"main\": \"index.js\",\n  \"scripts\": {\n    \"docs:dev\": \"vuepress dev\",\n    \"docs:build\": \"vuepress build\"\n  },\n  \"keywords\": [],\n  \"author\": \"\",\n  \"license\": \"ISC\",\n  \"devDependencies\": {\n    \"vuepress\": \"^1.9.10\",\n    \"@vuepress/theme-vue\": \"^1.9.10\"\n  }\n}\nEOF\n\nnpm run docs:dev","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"deprecated","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure that `.vuepress/config.js` uses `module.exports = { ... }` syntax for configuration. For VuePress v2, config files support TypeScript and ESM.","message":"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.","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":"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.","cause":"The `@vuepress/theme-vue` package is either not installed, or there's a typo in the `theme` configuration string in `.vuepress/config.js`.","error":"Error: Cannot find module '@vuepress/theme-vue'"},{"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.","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.","error":"404 Not Found (for pages with non-standard URL characters)"},{"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.","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.","error":"warning Overriding existing page xxx"}],"ecosystem":"npm"}