Before VUe3 you’ve probably used or heard of VuePress, which is a vuUe-based static website generator that can be used to write documents. For details, see the website of VuePress. But now there’s vue3, there’s Vite, and then there’s VitePress built on top of Vite. (The motivation for VitePress can be found on the official website.)

The advantage of vitepress

  • Based on Vite instead of WebPack, all faster startup times, hot reloads, etc
  • Use VUe3 to reduce the js payload

.vitepress/config.js

Improvements for VitePress

With the vue3

  1. Take advantage of VUe3’s improved template static analysis to string static content as much as possible
  2. Use the vite
  • Faster dev service startup
  • Hot updates are faster
  • Faster builds (using Rollup)

Lighter pages

  • Vue 3 tree shake + Rollup code separation
  • Metadata for all pages is not sent out in one request. The client gets the components and metadata of the new page together as it navigates
  • To use vue – the router
  • (WIP) I18N Localized data is requested as needed

The difference between

  • Less configuration for VitePress. Vitepress aims to strip away the complexity of current Vuepress and start again from its minimalist roots
  • Is future-oriented: the target browser is a browser that only supports native ES module imports. Encourage the use of native JS instead of escaping and subjectivities using CSS variables

The upgrade process

  1. Install vitepress
npm install vitepress
Copy the code

It turns out that when you use VuePress you have to have a Docs folder (if you don’t have one, you can create one yourself).

  1. Change the entry file to index.md

Note: Vuepress’s entry file is docs/readme.md, vitepress’s entry file is index.md, so change the name of the readme here. If index.md doesn’t have anything else, add something simple

-- Home: true title: home page lang: en-us heroText: BIFE Document library Tagline: This is your stage, looking forward to your wonderful actionText: Get Started actionLink: / new guidelines/first - day footer: MIT Licensed | Copyright © 2021 - present CoolDream -Copy the code
  1. Configure VitePress information
  • create.vitepressfolder
  • in.vitepressCreate a configuration fileconfig.js
  • inconfig.jsTo add configuration information
Export default {base: ", // The base path of the project title: "document", // The document title, which will be displayed in description: "front-end technical document", // Document description lastUpdated: 'last updated time, / / string | Boolean}Copy the code
  1. If you want to add the top right navigation, you can do it inthemeConfigadd
Module. exports = {themeConfig: {// top right nav: [{text: 'Home', link: '/ new user /first '}, {text: 'Components', link: 'http://bi-components.dev.weiyun.baidu.com:8523/#/component/inst' }, ], } }Copy the code

Note: Navigation links in nav should be case sensitive and have the same name as the linked file

  1. Add left navigation, also inthemeConfigadd

Need to pay attention to

The children link in Vuepress is the specific link, and the navigation name displayed is the title in each.md file

In Vitepress, children is an array of objects, text is the navigation name, and link is the real link

If there are multiple routes, write the default route at the end

Module. exports = {themeConfig: {// sidebar: ['/CHANGLOG':[{text: 'update log'}], '/': [{text: 'update log ', children: [{text: 'the first day, link:'/new guidelines/first - day}, {text: 'in the first week, link:'/new guidelines/first week - '}]}]],}}Copy the code
  1. Add a script topackage.jsonIn the
"scripts": {
    "dev": "vitepress dev docs",
    "build": "vitepress build docs",
    "notice": "sh scripts/notice.sh"
 },
Copy the code
  1. Uninstall vuepress
npm uninstall vuepress
Copy the code

Problems encountered during the upgrade

The switchover of multiple routes does not take effect

At first, the default route was written in the front, but it was found that the route was not updated during route switching and the default route was still the default route. Later, it was found that the default route needed to be written in the last

ThemeConfig :{// sidebar: {// Other routing in front of 'other-router':[], // Default routing in the last '/': [{text: 'new people need to know ', children: [{text:' new people need to know ', children: [{text: 'new people need to know ', children: [{text:' new people need to know ', children: [{text: Children: [{text: 'computer '}]}]}}Copy the code

Table format in Markdown (error during build)

After data type I can’t have a blank (bill (; ´_ ‘) wrong number of wrong rows, which led to a long search), as shown below

File internal link path must be.md or omit, cannot be other file type (build error)

Vitepress will convert the last level of the path to *.html (if it ends in /, go back to the index.md folder). If it is a different file type, if it is *.txt, the file will not be found

Markdown internal link cannot contain Chinese (build error)

Links in Markdown require HTTP protocol (build error)

An error is also reported if HTTP is not available