Common problems

Mr.Hope ... 2022-6-2 About 2 min

# Getting Help

If you ran into some issues, please make sure you are in the lastest version and tried removing node_modules folder then a clean install.

If the issue exists or there is somthing you don’t know how to solve, welcome to open a dicussion (opens new window). Questions are always welcome, no matter they are simple or not. You only need to make sure two points:

You have tried searching related docs through search box.
You are providing a detailed description in the discussion.
- If you don’t know how to config something, please describe what you want, and what you search or what section are you expecting to see the guidelines (so that we can improve our docs)
- If you are running into issues, provide related error log (by running vuepress dev <docs dir> --debug) and screenshots.

# `warning Overiding existing page xxx`

If you see warning Overiding existing page xxx while the dev process is starting up, please check your file structure.

You probably created two file with same path.

For example: a/b.md and a/b/readme.md will both be /a/b/

This will cause one page content be lost and it will also cause others issue.

# `xxx isn’t assign with a lang, and will return 'en-US' instead.`

If you see xxx isn’t assign with a lang, and will return 'en-US' instead. while the dev process is starting up, please check whether you set lang for every language.

If you only have one language, please set root lang like this way:

// .vuepress/config.js
const { config } = require("vuepress-theme-hope");

module.exports = config({
  locales: {
    "/": {
      // set language you want
      lang: "en-US",
    },
  },
});

1
2
3
4
5
6
7
8
9
10
11

# Some page settings are invalid

You can first review the documentation to see if the setting does not support partial configuration.

Support for partial configuration means that the theme allows the configuration of the page to override the global configuration of the same name (same function), but not all functions meet this setting. For the sake of project compilation speed, some projects will not be loaded during the compilation phase after the global configuration is disabled, and they cannot be enabled locally.

# Code block does not look right in light mode

I guess this is your fault. Please delete the $codeBgColor in .vuepress/styles/palette.styl. The default value of vuepress-theme-hope is light blue, while @vuepress/theme-default is dark blue.

# 404 when visiting some links

If you use non-URL-standard characters in category or tags, such as:

---
category: 软件
tags:
  - 谷歌浏览器
---

1
2
3
4
5

Then when you visit /category/软件 and /tag/谷歌浏览器/, you will be navigated to the 404 page.

This is a potentially breaking change introduced by vue-router in 3.4.6. Starting from 3.4.6, vue-router requires all non-standard URL paths to be handled by encodeURI and then added as a path to router.

The theme uses @vuepress/plugin-blog for blog support. This problem should be corrected in this plugin. Mr. Hope has already reported This Issue (opens new window), and submitted a PR (opens new window) for a temporary fix, but no one reviewed that PR.

Temporary solution

If you are using yarn, you can add the resolutions field:

{
  ...
  "resolutions": {
    "vue-router": "3.4.5"
  },
  ...
}

1
2
3
4
5
6
7

Go to your package.json to temporarily solve this problem.

# TypeScript problems

TypeScript problems

Changelog

Demos