Frequently Asked Questions
This document primarily covers common issues and solutions you might encounter while using the theme.
If you encounter any problems, you can first check the content below to see if there are related issues and solutions.
If you don't find what you're looking for, you can start a discussion with us via GitHub Discussions.
If you're certain that there's indeed an issue, please Open an issue on GitHub. In the issue, describe the specific details of the problem and, if necessary, try to provide a minimal reproduction package. We will address it as soon as possible.
What should I pay attention to when starting a discussion or raising an issue?
We welcome you to start discussions or ask any questions, regardless of how simple they may seem. Asking questions actively is good. However, please ensure the following three points:
You have already attempted to search the relevant documentation.
You provide a detailed description in your discussion.
You are not asking questions unrelated to VuePress, nor are you seeking technical support for custom implementations.
We will not answer questions like "How can I use a specific feature of the theme in isolation in my own project?" or "How can I implement a specific feature of the theme in my own project?".
How to update the theme?
You can update the theme using the vp-update command.
vp-update is a CLI tool maintained by the VuePress team. It helps you check for the latest versions of VuePress-related themes, plugins, etc., within your project and automatically installs the dependencies for you. It requires no prior installation; you can run it directly via npx vp-update.
Copy and run the following command in your project:
npx vp-updatepnpm dlx vp-updateyarn dlx vp-updateHow do I migrate collections config ?
Upgrade to 1.0.0-rc.165 and later versions,, the theme automatically migrates legacy blog / notes configuration to collections at build time, so in most cases no manual changes are needed.
A few cases still require your attention. The most common one: you have configured collections while keeping your legacy blog / notes — the legacy config is then silently ignored.
See the Migration Guide for the complete migration rules, a manual migration example, and a verification checklist.
Why don't new features take effect after updating the theme version?
Because VuePress takes a long time to fully compile all markdown files in the source directory when starting the dev server, the theme implements caching for markdown compilation to improve startup speed. After updating the theme and restarting the dev server, if the markdown files in the source directory haven't changed, the compilation is skipped and the cache is used directly. This can cause new features related to markdown not to take effect.
Simply delete the cache files and restart:
Method 1: Directly delete the
.vuepress/.cachedirectory.Method 2: Add the
--clean-cacheparameter when starting the dev server command:vuepress dev docs --clean-cache
Why don't changes to theme plugin configurations take effect?
Simply delete the cache files and restart:
Method 1: Directly delete the
.vuepress/.cachedirectory.Method 2: Add the
--clean-cacheparameter when starting the dev server command:vuepress dev docs --clean-cache
After updating dependencies, restart prompts import "xxxx" not exist
Sometimes, after updating the theme and related dependencies, there might be an issue where the package manager fails to correctly generate the new dependency tree, leading to errors like "module not found" when importing certain dependencies. At this point, the dependency lock files (like package-lock.json or pnpm-lock.yaml) might be corrupted.
Please directly delete the dependency lock files (package-lock.json, pnpm-lock.yaml, etc.) and the node_modules directory, then reinstall the dependencies.
How to hide the page footer?
You can hide the footer by adding footer: false in the frontmatter of the Markdown file.
---
footer: false
---
contentConfiguration Documentation: frontmatter > Footer
Or you can hide the footer for all pages on the main site by adding footer: false in the theme configuration file.
export default defineUserConfig({
theme: plumeTheme({
footer: false,
})
})Configuration Documentation: Theme Configuration
Build error: JavaScript heap out of memory
When executing npm run docs:build, you encounter an error similar to:
<--- Last few GCs --->
[69161:0x7fe63aa00000] 137006 ms: Mark-sweep (reduce) 2048.2 (2082.5) -> 2048.2 (2082.5) MB, 1205.3 / 0.0 ms (average mu = 0.123, current mu = 0.012) allocation failure; scavenge might not succeed
[69161:0x7fe63aa00000] 139327 ms: Mark-sweep (reduce) 2048.2 (2082.5) -> 2048.2 (2082.5) MB, 1231.5 / 0.0 ms (average mu = 0.102, current mu = 0.015) allocation failure; scavenge might not succeed
<--- JS stacktrace --->
FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
----- Native stack trace -----
1: 0x107ce7c84 node::Abort() [/path/to/node]
...This is due to insufficient Node.js memory.
Modify the Node.js memory limit by adding the following environment variables:
Method 1: In the current terminal session:
export NODE_OPTIONS="--max_old_space_size=8192"
npm run docs:buildNote that this method is only effective for the current terminal session.
Method 2: In the local environment:
If you need to keep this environment variable long-term, you can modify the Node.js memory limit in your local environment:
Install
cross-envin your projectnpmnpm install -D cross-envpnpmpnpm add -D cross-envyarnyarn add -D cross-envAdd
scriptsinpackage.json:{ "scripts": { "docs:build-local": "cross-env NODE_OPTIONS=\"--max_old_space_size=8192\" vuepress build docs --clean-cache --clean-temp" } }
When building locally, use npm run docs:build-local to build the package.
Method 3: In GitHub Actions:
Modify the .github/workflows/deploy.yml file and add the following environment variables:
# ...
- name: Build VuePress site
env:
NODE_OPTIONS: --max_old_space_size=8192
run: npm run docs:build
# ...