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是否配置成功验证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/目录

位于/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中添加如下项。

remixiconremixicon

//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上时出现的提示悬浮在hostname上时出现的提示

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

添加新评论

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

    obaby 02-12

    折腾使人充实

      02-12 回复 @obaby

      云笔记好看吧?

    白雾茫茫丶 02-12

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

      02-12 回复 @白雾茫茫丶

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