Frequently Asked Questions

About 949 wordsAbout 3 min

2025-10-08

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.

Copy and run the following command in your project:

npm

npx vp-update

pnpm

pnpm dlx vp-update

yarn

yarn dlx vp-update

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/.cache directory.
Method 2: Add the --clean-cache parameter when starting the dev server command:
```
vuepress dev docs --clean-cache
```

Why don't changes to theme plugin configurations take effect?

This issue commonly occurs when modifying configurations for plugins.markdownEnhance, plugins.markdownPower, plugins.markdownImage, and plugins.markdownMath. The reason is the same as Why don't new features take effect after updating the theme version?. Therefore,

Simply delete the cache files and restart:

Method 1: Directly delete the .vuepress/.cache directory.
Method 2: Add the --clean-cache parameter 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.

You can hide the footer by adding footer: false in the frontmatter of the Markdown file.

post.md
---
footer: false
---

content

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

.vuepress/config.ts
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:build

Note 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-env in your project

npm

npm install -D cross-env

pnpm

pnpm add -D cross-env

yarn

yarn add -D cross-env

Add scripts in package.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

# ...

Contributors

pengzhanbo

Changelog

7/15/26, 1:40 PM

View All Changelog

0daf2-docs: improve docs (#929)on 7/15/26
47968-docs: update docson 2/15/26
38505-docs: update en docs (#708)on 10/9/25