vuepress-theme-plume/docs/en/questions.md

---
title: Frequently Asked Questions
createTime: 2025/10/08 08:47:36
permalink: /en/faq/
article: false
---

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](https://github.com/pengzhanbo/vuepress-theme-plume/discussions/new?category=q-a).

If you're certain that there's indeed an issue, please
[Open an issue](https://github.com/pengzhanbo/vuepress-theme-plume/issues/new?assignees=pengzhanbo&labels=bug&projects=&template=bug-report.zh-CN.yml&title=%5BBug%5D)
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.

::: details 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:

1. You have already attempted to search the relevant documentation.
2. You provide a detailed description in your discussion.
3. 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-to

```sh
npx 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**:

1. Method 1: Directly delete the `.vuepress/.cache` directory.
2. Method 2: Add the `--clean-cache` parameter when starting the dev server command:

   ```sh
   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?](#why-dont-new-features-take-effect-after-updating-the-theme-version).
Therefore,

**Simply delete the cache files and restart**:

1. Method 1: Directly delete the `.vuepress/.cache` directory.
2. Method 2: Add the `--clean-cache` parameter when starting the dev server command:

   ```sh
   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.

```md title="post.md"
---
footer: false
---

content
```

[Configuration Documentation: **frontmatter > Footer**](../config/frontmatter/basic.md#footer){.read-more}

Or you can hide the footer for all pages on the main site by adding `footer: false` in the theme configuration file.

```ts title=".vuepress/config.ts"
export default defineUserConfig({
  theme: plumeTheme({
    footer: false, // [!code ++]
  })
})
```

[Configuration Documentation: **Theme Configuration**](../config/theme.md#footer){.read-more}

## Build error: `JavaScript heap out of memory`

When executing `npm run docs:build`, you encounter an error similar to:

```sh
<--- Last few GCs --->

[69161:0x7fe63aa00000]   137006 ms: xxxxxx
[69161:0x7fe63aa00000]   139327 ms: xxxxxxxx

<--- JS stacktrace --->
FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
----- Native stack trace -----

1: 0x107ce7c84 xxxxxxxxxxxx
...
```

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**:

```sh
export NODE_OPTIONS="--max_old_space_size=8192"
npm run docs:build
```

==Note that this method is only effective for the current terminal session.=={.warning}

**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:

:::: steps

- Install `cross-env` in your project

  ::: npm-to

  ```sh
  npm install -D cross-env
  ```

  :::

- Add `scripts` in `package.json`:

  ```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:

```yaml
# ...
- name: Build VuePress site
  env: # [!code ++:2]
    NODE_OPTIONS: --max_old_space_size=8192
  run: npm run docs:build

# ...
```