VuePress Hope主题

使用此主题构建属于自己的知识库，可用Vercel部署

前几天成功将云笔记迁移至Vuepress，解决了我一个最焦虑的问题：原由Docsify驱动的云笔记不能加载favicon。当然，界面也更加好看。比起Docsify，Vuepress除了具有Docsify基本的功能（搜索、目录、代码高亮），它还支持许多功能扩展。这篇文章用于记录如何搭建Vuepress，以便日后查阅，也可作为教程观看。云笔记

Vuepress-Hope是Vuepress的一款主题，也是NPM上下载数量最多，最多人喜欢的Vuepress主题。它受如此欢迎的原因就是它具有丰富的插件支持和功能配置，可以最大化尽可能随心所欲地搭建自己想要的站点。除了搭建成文档管理系统（云笔记），它也可以驱动为一个博客。现在有很多人使用Vuepress-Hope搭建文档和博客。查看

官网的文档可能比较晦涩难懂，我也是研究了两天才得以将云笔记上线。它更趋向于文档，而不适合作为教程观看，因此你可以观看这篇文章从而搭建一个与我一模一样的云笔记。

若你在阅读我的搭建教程时遇到了问题，可能是由于Vuepress-Hope主题更新导致此文章部分内容过时，这时你可以前往Vuepress-Hope官网查看文档，不过其他部分仍然可以继续观看。

那么让我们开始吧。

运行环境

IDE的话，这里推荐使用VSCode，它能够很好地支持Vuepress-Hope的语法，并提供类型检查、代码补全等功能。VSCode

除此之外，你的电脑还需要有NodeJS环境，下载最新版即可。NodeJS官网

这里建议NodeJS过旧的升级到最新版，因为本教程是使用Vuepress-Hope最新版做演示，而他们所需要的NodeJS版本很高。

安装完NodeJS后，建议使用pnpm包管理器，因为Vuepress-Hope的官网全部教程都是使用此包管理器，且我使用的也是。

在终端中输入如下命令激活pnpm包管理器。

corepack enable
corepack prepare pnpm@latest --activate

到这一步完成后，就可以打开PowerShell，输入pnpm，看看是否安装成功。

验证pnpm是否配置成功

安装Vuepress-Hope

使用cd命令跳转到你要安装的目录，输入以下命令初始化目录，并安装Vuepress-Hope。这里我将项目安装到A盘根目录，并将文件夹命名为vuepress-demo。

cd A:/
pnpm create vuepress-theme-hope vuepress-demo

在这一步后，会出现如下图所示的选择语言界面，这里可以选择使用中文。按键盘的上下键选择后，按回车确定。

选择显示语言

选择显示语言后的选项可以根据自己的需要自由设置，或者和我图中的保持一致。

创建完成

开始修改配置

打开VSCode，打开创建的项目文件夹，就可以开始编辑了。

它的项目文件夹结构如下。

项目文件夹结构

src为文档目录，在生成静态目录时就是渲染这个文件夹里面的markdown。.vuepress文件夹为配置和样式文件夹，public文件夹用于放置静态文件，styles用于存储样式，主题色就可以在这里面定义。config.ts为总配置文件，navbar.ts为导航栏配置，sidebar.ts为侧边栏配置，theme.ts为主题配置。在src文件夹下还有一个README.md文件，这里面存放了Vuepress-Hope为我们生成的强大主页模板，我们可以基于这个修改。

配置导航栏

这个在navbar.ts中配置。这里可配置的导航栏情况有以下几种，可以直接查看代码。

//navbar.ts
import { navbar } from "vuepress-theme-hope";

export default navbar([
  "/", /* 单链接 */
  {
    text: "V2 文档",  /* 链接、图标、链接 */
    icon: "book",
    link: "https://theme-hope.vuejs.press/zh/",
  },
  {
    text: "指南",
    icon: "lightbulb",
    prefix: "/guide/",
    children: [ /* 嵌套的链接 */
      {
        text: "Bar",
        icon: "lightbulb",
        prefix: "bar/",
        children: ["baz", { text: "...", icon: "ellipsis", link: "" }],
      },
      {
        text: "Foo",
        icon: "lightbulb",
        prefix: "foo/",
        children: ["ray", { text: "...", icon: "ellipsis", link: "" }],
      },
    ],
  },
]);

之后可以打开终端预览这个界面。使用如下命令可以在localhost:8080预览。

pnpm docs:dev

导航栏

如果要填写外链时，要填写链接名text和链接link，图标icon是可选的，否则主题会将其渲染为内链。

此外，导航栏可以开启一些额外功能，如我的云笔记开启了全屏、切换主题颜色、切换夜间模式。这个在后面会介绍。

侧边栏

侧边栏比较复杂，详细的可以前往官方文档阅读，这里分享一下我自己的配置。我的云笔记中，比如MySQL笔记下有【基础知识】、【高级应用】等三个目录，我想在进入MySQL根目录时显示其他三个目录的标题。在点进这三个目录中的其中一个时，可以再显示这个目录内的其他目录，如下图。

位于/MySQL/目录

位于/MySQL/基础知识/目录

//sidebar.ts
import { sidebar } from "vuepress-theme-hope";

export default sidebar({
  '/mysql/': [
    '/mysql/基础知识/',
    '/mysql/MySQL基础/',
    '/mysql/高级应用/'
  ],
  '/mysql/基础知识/': [
    '/mysql/基础知识/认识数据库.md',
    '/mysql/基础知识/数据表操作.md',
    '/mysql/基础知识/数据库操作.md',
    '/mysql/基础知识/MySQL数据类型.md',
    '/mysql/基础知识/MySQL数据引擎.md'
  ]
});

再比如我的汇编速查中只有一个笔记，没有其他子目录了，我想让进入它的时候显示其他笔记，如下图。

无子目录时显示其他笔记

//sidebar.ts
import { sidebar } from "vuepress-theme-hope";

export default sidebar({
  '/assembly/': [
    '/assembly/',
    '/awt/',
    '/crawler/',
    '/css/',
    '/django/',
    '/fastapi/',
    '/flask/',
    '/html/',
    '/java/',
    '/javascript/',
    '/linux/',
    '/mongodb/',
    '/mysql/',
    '/nlp/',
    '/pyqt6/',
    '/python/',
    '/redis/',
    '/swing/',
    '/tornado/'
    ]
});

这里面这些目录的名称就是你想展示的其他目录的名称。

这里不得不提一下，对于Vuepress的目录结构，和路由之间是有一定配合的。由于Vuepress最后构建的页面是纯静态页面，我们默认进入一个路径时访问的是index.html，它是用README.md文件渲染的，而其他路径，如【基础知识.html】就是用【基础知识.md】渲染的。所以你可以看到，我的MySQL笔记中有一些路径是以【.md】结尾的，有些则是以【/】结尾的。以【某某/】结尾的文件就相当于【某某/README.md】。

页面信息

每个Markdown前面可以用一些简单的YAML语法定义这个页面的信息。如title代表这个网页的名称，description则为这个网页的描述。

如现在我改一下根目录README.md的文件，如下。

---
title: 这是网页标题
description: 这是网页描述
author: 作者名称
---

## 这是一个二级标题

这是一个正文。

渲染的网页

由于这是根目录的README.md文件，因此我们往往会将其渲染为主页，这时我们可以在开始的YAML格式加一条：home: true。

渲染成主页

我们可以加一些元素，让其看起来更像主页。下面的代码是官方预设的模板代码，我将其精简了一下。

---
home: true
icon: home
title: 项目主页
heroImage: /logo.svg
bgImage: https://theme-hope-assets.vuejs.press/bg/6-light.svg
bgImageDark: https://theme-hope-assets.vuejs.press/bg/6-dark.svg
bgImageStyle:
  background-attachment: fixed
heroText: 项目名称
tagline: 你可以在这里放置或是整个项目的描述。
actions:
  - text: 使用指南
    icon: lightbulb
    link: ./demo/
    type: primary

  - text: 文档
    link: ./guide/

highlights:
  - header: 在 Markdown 中添加你想要的内容
    description: 我们扩展了标准的 CommonMark 规范，为你添加了成吨功能。
    image: /assets/image/markdown.svg
    bgImage: https://theme-hope-assets.vuejs.press/bg/2-light.svg
    bgImageDark: https://theme-hope-assets.vuejs.press/bg/2-dark.svg
    bgImageStyle:
      background-repeat: repeat
      background-size: initial
    features:
      - title: 链接检查
        icon: clipboard-check
        details: 检查 Markdown 链接
        link: https://theme-hope.vuejs.press/zh/guide/markdown/others.html#link-check

      - title: 提示容器支持
        icon: box-archive
        details: 用样式装饰 Markdown 内容
        link: https://theme-hope.vuejs.press/zh/guide/markdown/hint.html

      - title: GFM 警告
        icon: bell
        details: GFM 风格的警告容器
        link: https://theme-hope.vuejs.press/zh/guide/markdown/alert.html

      - title: 选项卡
        icon: table-columns
        details: 使用选项卡对相似内容进行分组
        link: https://theme-hope.vuejs.press/zh/guide/markdown/tabs.html

copyright: true
footer: 使用 <a href="https://theme-hope.vuejs.press/zh/" target="_blank">VuePress Theme Hope</a> 主题 | MIT 协议, 版权所有 © 2019-present Mr.Hope
---

这是项目主页的案例。你可以在这里放置你的主体内容。

想要使用此布局，你需要在页面 front matter 中设置 `home: true`。

配置项的相关说明详见 [项目主页配置](https://theme-hope.vuejs.press/zh/guide/layout/home/)。

让主页更丰富

建议为每个页面都配置title，这样网页就可以显示正确的标题，否则它会将markdown的第一个一级标题作为网页的标题。

其他小元素

图标

这里我将图标改为了Remixicon。它给的图标库有iconfont、fontawesome等。

首先下载Remixicon图标库，然后将其内容解压，放在/src/public/remixicon/文件夹下，然后在theme.ts中添加如下项。

remixicon

//theme.ts
import { hopeTheme } from "vuepress-theme-hope";
import navbar from "./navbar.js";
import sidebar from "./sidebar.js";

export default hopeTheme({
  //...
  iconAssets: "/remixicon/remixicon.css",
  iconPrefix: 'ri-',
  //...
});

接下来，将要添加的图标处加一个icon: iconname，就可以添加图标了，如为之前导航栏配置的主页添加一个房子的图标。

//navbar.ts
import { navbar } from "vuepress-theme-hope";

export default navbar([
  {
    text: "主页",  /* 链接、图标、链接 */
    icon: "home-line",
    link: "/",
  }
]);

添加图标

页脚

页脚可以展示版权信息，备案号等。首先需要在theme.ts中设置displayFooter: true。footer是页脚默认内容，支持HTML语法，就可以在这里面输入链接。

//theme.ts
import { hopeTheme } from "vuepress-theme-hope";
import navbar from "./navbar.js";
import sidebar from "./sidebar.js";

export default hopeTheme({
  footer: "<a href='https://example.com'>备案号： xxxx</a>",
  displayFooter: true,
});

由于这里面设置的是默认页脚，在上方展示的首页markdown中也有一个footer的选项，这个页脚配置会将theme.ts中的页脚配置覆盖掉，这一点要注意。

页脚展示

在页脚右方的是版权信息，这个也是在theme.ts中配置，用copyright配置。同样，它也会被markdown的内容覆盖掉。

//theme.ts
import { hopeTheme } from "vuepress-theme-hope";
import navbar from "./navbar.js";
import sidebar from "./sidebar.js";

export default hopeTheme({
  copyright: '版权信息',
});

深色模式、全屏模式

在theme.ts中设置darkmode的值以更改，它有以下几个值：

"switch": 在深色模式，浅色模式和自动之间切换 (默认)
"toggle": 在深色模式和浅色模式之间切换
"auto": 自动根据用户设备主题或当前时间决定是否应用深色模式
"enable": 强制深色模式
"disable": 禁用深色模式

全屏模式则可以在theme.ts中设置fullScreen: true。

主题色

在/src/.vuepress/public/pallete.scss中可以设置主题色，修改$theme-color的值即可。

除此之外，还可以设置多个主题色，以在导航栏中激活选择主题色。这需要修改/src/.vuepress/public/config.scss的中$theme-color的值。如：

$theme-colors: #c0392b, #d35400, #f39c12, #27ae60, #16a085, #2980b9, #8e44ad, #2c3e50,
  #7f8c8d;

设置主题色

插件

搜索功能

首先先在shell中运行下面的脚本，添加搜索插件。

pnpm add -D vuepress-plugin-search-pro

然后在config.ts中添加如下代码。

// .vuepress/config.ts
import { defineUserConfig } from "vuepress";
import { searchProPlugin } from "vuepress-plugin-search-pro";

export default defineUserConfig({
  plugins: [
    searchProPlugin({
      // 索引全部内容
      indexContent: true,
      // 为分类和标签添加索引
      customFields: [
        {
          getter: (page) => page.frontmatter.category,
          formatter: "分类：$content",
        },
        {
          getter: (page) => page.frontmatter.tag,
          formatter: "标签：$content",
        },
      ],
    }),
  ],
});

为标签和分类添加索引这个在我的云笔记中没有添加，因为我用不到。

默认启用的插件

Vuepress-Hope内置了一些插件，这些插件是默认启用的，你可以在配置文件中手动它他们关闭。

代码复制：vuepress-theme-hope 将主题选项中的 plugins.copyCode 选项作为插件选项提供给 vuepress-plugin-copy-code2。若你不需要这个插件，在theme.ts的plugin中将这个值设为false即可，下面的插件亦是如此。
图片预览：vuepress-theme-hope 将主题选项中的 plugins.photoSwipe 选项作为插件选项提供给 vuepress-plugin-photo-swipe。
版权：vuepress-theme-hope 将主题选项中的 plugins.copyright 作为插件选项提供给 vuepress-plugin-copyright2。该插件不是默认启用的。

其他配置

在theme.ts文件中存在一些其他的配置，鼠标悬浮于上面可以显示它们的详细信息。

悬浮在hostname上时出现的提示

官方文档也对这些变量做了详细的解释。

添加新评论

点击评论者的头像以回复。

kirari 8 天前

十分感谢，不过重新下载一边已经解决了，看来最好的解决办法就是重构哈哈

kirari 9 天前

我今天随便上传了一个没修改的构建成功了，尴尬看来是乱折腾弄错了配置

棋 9 天前回复 @kirari

有什么问题可以添加页脚的联系方式，我很乐意帮你解决问题

kirari 9 天前

怎么部署呢，我今天整了好久没有成功，报了莫名其妙的错，显示我的config.ts的一行字符是单引号也就是`' "`的形式，之后我去检查了文件是` " " `的形式，真是摸不清头脑

obaby 02-12

折腾使人充实

棋 02-12 回复 @obaby

云笔记好看吧？

白雾茫茫丶 02-12

你是真的能折腾呀，有空就是好，啥都能捣鼓一下

棋 02-12 回复 @白雾茫茫丶

哈哈，最近没课，就有空研究这些，也快放假了。