升级

Vuepress 终于进入了预发布阶段，本文将介绍如何升级到 Vuepress2.0.0-RC.8。

---

• 安装 Vuepress2.0.0-RC.8
• 安装插件
• 复制文件
• 配置 Vuepress
• 开始使用 Vuepress
• FAQ
• Links

安装 Vuepress2.0.0-RC.8

mkdir -p vuepress2.0.0-RC.8 && cd vuepress2.0.0-RC.8
yarn init
yarn add -D vuepress@next     # 安装 vuepress
yarn add -D @vuepress/bundler-vite@next @vuepress/theme-default@next       # 安装打包工具和主题

安装插件

npm i -D @vuepress/plugin-copy-code@next
npm i -D @vuepress/plugin-container@next
npm i -D @vuepress/plugin-docsearch@next
npm i -D @vuepress/plugin-pwa@next
npm i -D @vuepress/plugin-sitemap@next

复制文件

• 将原来的 vuepress 里的文章复制到 vuepress2.0.0-RC.8/docs 下
• 如果有问题记得删除 docs/.vuepress/{.cache,.temp} 这两个文件

配置 Vuepress

• Git 配置

  •   .vuepress/.temp
      .vuepress/.cache
      .vuepress/dist
      node_modules
      .vscode
      .idea
      .git
      secretKeyConf.js
    

• seo 爬虫配置

  •   User-agent: *
      Allow: /
    

const navConf = require('../../config/navConf.js')
import pluginConf from '../../config/pluginConf.js'
const sidebarConf = require('../../config/sidebarConf.js')
const headConf = require('../../config/headConf.js').default

import { defaultTheme } from '@vuepress/theme-default'
import { viteBundler } from '@vuepress/bundler-vite'
import { defineUserConfig } from 'vuepress'

export default defineUserConfig({
    bundler: viteBundler({
      viteOptions: {},
      vuePluginOptions: {},
    }),

    lang: 'zh-CN',
    title: 'iEnote',
    description: 'iEnote 是一个记录 IT 知识点的文档生成器。IT 知识，文档管理，文档记录，文档生成器',
    // base: '/v2/',  // 部署时如果地址是：https://192.168.1.20/v2  这里的路径就要写为 /v2/ 如果是 / 就需要注释此项。
    
    head: headConf,

    plugins: pluginConf,
    shouldPrefetch: false,

    markdown: {
        toc: {
            level: [2],
        },
    },
    
    theme: defaultTheme({
        logo: '/favicon.svg',
        // logo: 'icon.svg',

        docsDir: 'docs',

        navbar: navConf,

        sidebar: sidebarConf,
        sidebarDepth: 0,  //https://v2.vuepress.vuejs.org/zh/reference/default-theme/config.html#sidebardepth

        lastUpdatedText: '上次更新',
        contributorsText: '贡献者',

        tip: '提示',
        warning: '注意',
        danger: '警告',

        notFound: [
            '这里什么都没有',
            '我们怎么到这来了？',
            '这是一个 404 页面',
            '看起来我们进入了错误的链接',
            ],
        backToHome: '返回首页',

        toggleColorMode: '切换夜间模式',
        toggleSidebar: '切换侧边栏',

        themePlugins: {
            externalLinkIcon: false,
        },
        markdown: {
            headers: {
                level: [2,3],
            },
                    
        }, 
    }),
  })

import secretKeyConf from './secretKeyConf';
import { containerPlugin } from '@vuepress/plugin-container';
import { pwaPlugin } from '@vuepress/plugin-pwa';
import { docsearchPlugin } from '@vuepress/plugin-docsearch';
import { sitemapPlugin } from '@vuepress/plugin-sitemap';
import { backToTopPlugin } from '@vuepress/plugin-back-to-top';
import { copyCodePlugin } from '@vuepress/plugin-copy-code';

export default [
    docsearchPlugin({
        apiKey: secretKeyConf.apiKey,
        appId: secretKeyConf.appId,
        indexName: secretKeyConf.indexName,
        locales: {
          '/': {
            placeholder: '搜索文档',
            translations: {
              button: {
                buttonText: '搜索文档',
              },
            },
          },
          '/zh/': {
            placeholder: '搜索文档',
            translations: {
              button: {
                buttonText: '搜索文档',
              },
            },
          },
        },
    }),

	sitemapPlugin({
      hostname: 'https://www.echoxu.cn',
    }),

    pwaPlugin({
        skipWaiting: true,
    }),

    backToTopPlugin({
        progress: false,
    }),

    copyCodePlugin({
        showInMobile: false,
    }),

    // badge-note
    containerPlugin(
    {
        type: 'note',
        before: (info) => `<span class="badge note">${info ? `<summary>${info}</summary>` : ''}\n`,
        after: () => '</span>\n',
    }), 

    // 分栏
    containerPlugin({
        type: 'multi-column',
        before: (info) =>
        `<div data-callout="multi-column" class="custom-container multi-column callout">${info ? `<p class="custom-container-title multi-column">${info}</p>`  : ''}\n`,
        after: () => '</div>\n',
    }),

    // 可展开的容器
    containerPlugin({
        type: 'collapselist',
        before: (info) => `<details class="custom-container collapselist">${info ? `<summary>${info}</summary>` : ''}\n`,
        after: () => '</details>\n',
    }), 

    // 容器---有边框无背景色的容器
    containerPlugin({
        type: 'col-border',
    }),

    // 灰色背景的容器块
    containerPlugin({
        type: 'col-bgwithgray',   
    }),

    // 自定义的容器 (类 notion 样式) ---无标题色，标题有 border-bottom
    containerPlugin({
        type: 'col-notitlebg',
    }),

    // 自定义的容器 (类 notion 样式) ---浅橙色
    containerPlugin({
        type: 'col-lightorange',
    }),

    // 自定义的容器 (类 notion 样式) ---浅绿色
    containerPlugin({
        type: 'col-lightgreen',
    }),

    // 自定义的容器 (类 notion 样式) ---银灰色
    containerPlugin({
        type: 'col-lightargent',   
    }),

    // 自定义的容器 (类 notion 样式) ---浅红色
    containerPlugin({
        type: 'col-lightred',   
    }),

    // 高亮块-蓝色
    containerPlugin({
        type: 'highlight-blue',
    }),
    
    // 高亮块-橙色
    containerPlugin({
        type: 'highlight-orange',
    }),

    // 高亮块-红色
    containerPlugin({
        type: 'highlight-red',
    }),

    // 高亮块-绿色
    containerPlugin({
        type: 'highlight-green',
    }),

    // 高亮块-紫色
    containerPlugin({
        type: 'highlight-purple',
    }),

    // 高亮块-灰色
    containerPlugin({
        type: 'highlight-gray',
    }),

    // 容器---图片并排显示
    containerPlugin({
        type: 'img-grid',
    }),

    // 容器--- 文字单行显示
    containerPlugin({
        type: 'content-flex',
    }),


    // 可扩展的提示块
    containerPlugin({
        type: 'details-note',
        before: (info) => `<details class="custom-container details-note">${info ? `<summary>${info}<svg width="16" height="16" viewBox="0 0 48 48" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M19 12L31 24L19 36" stroke="#245bdb" stroke-width="4" stroke-linecap="round" stroke-linejoin="round"/></svg></summary> ` : ''}\n<div class="details-content">`,
        after: () => '</div></details>\n',
    }), 

    containerPlugin({
        type: 'details-tip',
        before: (info) => `<details class="custom-container details-tip">${info ? `<summary>${info}<svg width="16" height="16" viewBox="0 0 48 48" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M19 12L31 24L19 36" stroke="#245bdb" stroke-width="4" stroke-linecap="round" stroke-linejoin="round"/></svg></summary> ` : ''}\n<div class="details-content">`,
        after: () => '</div></details>\n',
    }),

    containerPlugin({
        type: 'details-warning',
        before: (info) => `<details class="custom-container details-warning">${info ? `<summary>${info}<svg width="16" height="16" viewBox="0 0 48 48" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M19 12L31 24L19 36" stroke="#245bdb" stroke-width="4" stroke-linecap="round" stroke-linejoin="round"/></svg></summary> ` : ''}\n<div class="details-content">`,
        after: () => '</div></details>\n',
    }),

    containerPlugin({
        type: 'details-danger',
        before: (info) => `<details class="custom-container details-danger">${info ? `<summary>${info}<svg width="16" height="16" viewBox="0 0 48 48" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M19 12L31 24L19 36" stroke="#245bdb" stroke-width="4" stroke-linecap="round" stroke-linejoin="round"/></svg></summary> ` : ''}\n<div class="details-content">`,
        after: () => '</div></details>\n',
    }),

    containerPlugin({
        type: 'details-example',
        before: (info) => `<details class="custom-container details-example">${info ? `<summary>${info}<svg width="16" height="16" viewBox="0 0 48 48" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M19 12L31 24L19 36" stroke="#245bdb" stroke-width="4" stroke-linecap="round" stroke-linejoin="round"/></svg></summary> ` : ''}\n<div class="details-content">`,
        after: () => '</div></details>\n',
    }), 
]

module.exports = {
    '/linux/': [
        {
          text: '入门',
          children: [
            '/linux/linux-basic/README.md',
            '/linux/shell/README.md',
            '/linux/rpm/README.md',
            '/linux/faq/README.md',
          ],
        },
        {
            text: '进阶',
            children: [
                '/linux/linux-fun/README.md',
            ],
        },
        {
            text: '拓展',
            children: [
                '/linux/basicserver/README.md',
            ],
        },
    ],
    '/Inbox/': [
        {
            text: '已归档',
            children: [
                '/Inbox/vuepress/README.md',
            ],
        },
        {
            text: '未归档',
            children: [
                '/Inbox/others/README.md',
                '/Inbox/openwrt/README.md',
                '/Inbox/vps/README.md',
                
            ],
        },
    ],
    '/Inbox/vuepress/pages': [
        {
            text: '安装',
            children: [
                '/Inbox/vuepress/pages/frontend-env.md',
                '/Inbox/vuepress/pages/vueprss.md',
            ],
        },

        {
            text: '指南',
            children: [
                '/Inbox/vuepress/pages/outline-notes.md',
                '/Inbox/vuepress/pages/tab-usecase.md',
                '/Inbox/vuepress/pages/text-highlighting.md',
                '/Inbox/vuepress/pages/highlight-blocks.md',
                '/Inbox/vuepress/pages/vuepress-anchor.md',
                '/Inbox/vuepress/pages/vuepress-algoliasearch.md',
                '/Inbox/vuepress/pages/anchor-right.md',
                '/Inbox/vuepress/pages/vuepress-container.md',
                '/Inbox/vuepress/pages/override_default_sidebar.md',
                '/Inbox/vuepress/pages/upgrade-to-vuepress2.0.0-RC.8.md',
                '/Inbox/vuepress/pages/deploy-to-alioss.md',
            ],
            // collapsible: true,
        },

        {
            text: '排版',
            children: [
                '/Inbox/vuepress/pages/how-to-typographical.md',
            ],
        },
    ],
    '/Devops/': [
        {
            text: 'CI/CD',
            children: [
                '/Devops/git/README.md',
            ],
            // collapsible: true,
        },
    ],
    '/backend_development/': [
        {
            text: 'Golang',
            children: [
                '/backend_development/Golang/README.md',
            ],
        },

        {
            text: 'Python',
            children: [
                '/backend_development/Python/README.md',
            ],
        },

        {
            text: 'MySQL',
            children: [
                '/backend_development/mysql/README.md',
            ],
        },

        {
            text: 'Nginx',
            children: [
                '/backend_development/nginx/README.md',
            ],
        },
    ],

    // '/backend_development/mysql/pages': [

    // ],

    '/front-end_development': [
        {
            text: 'Javascript',
            children: [
                '/front-end_development/vue/README.md',
            ],
        },
    ]
}

开始使用 Vuepress

在 package.json 中添加一些 scripts:

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs",
    "deploy": "bash deploy.sh"
  }
}

• 启动开发服务器: yarn docs:dev
• 构建项目: yarn docs:build

FAQ

Vuepress2.0.0.0-RC.8 有什么不同？

• 原来的 vuepress-plugin-anchor-right 插件无法使用了，选择用默认主题提供的 [[toc]] 语法加上自定义 CSS 来实现，但无法实现标题栏 active 后的效果，缺点是：每篇文件都要添加 [[toc]] 标签。
• permalink 设置失效：假如有一篇文章文件名叫: 前端环境配置.md 其通过 Frontmatter 语法: permalink: /Inbox/how-to-use-vuepress/yarnandnodejs 生成永久链接，然后在 md 文件中通过 [安装 vuepress 前的环境准备](./pages/前端环境配置.md) 无法跳转到该文章的永久链接，提示 404,它默认生成的是 http://localhost:8080/Inbox/vuepress/pages/前端环境配置.html,只有注释掉文章的 permalink 才能跳转，这样就导致原来的 siderbar 规则也生效

我做了什么？

• 目录结构调整: 假如我有 vuepress 系列文章，新建 Inbox/vuepress 目录，这个目录用来存储 vuepress 总路由文件,即 README.md，然后创建 Inbox/vuepress/pages 目录，用来存储该系列的所有文章。
• sidebar 设置：新增 '/Inbox/vuepress/pages' 规则，指向 pages 下的每个文件。
• 文件名全改为英文，不再使用中文命令，因为 vuepress 默认是按文件名生成 .html 文件，但浏览器会对中文进行编码，对 seo 不友好。

Links

• 相关文章: 升级到 Vuepress2.0.0-beta.61