使用 VuePress 建立一个知识笔记站点

发表于 分类于

本文在 VuePress 上的预览

安装 VuePress

参考 VuePress - 手动安装

初始化

首先创建并进入一个新的文件夹，打开终端，执行下面的命令

1
yarn init

安装 VuePress v2

1
yarn add -D vuepress@next

设置快捷命令

在 package.json 中添加一些 scripts

md 指的是存放文档的文件夹，可以随意命名 

1
2
3
4
"scripts": {
  "dev": "vuepress dev md",
  "build": "vuepress build md"
}

即可使用 yarn dev 替代 yarn vuepress dev md

踩坑：
主文件夹用 docs 会与自动生成侧栏冲突，使相关功能无法生效

创建文档

1
2
mkdir note
echo '# Hello VuePress' > note/README.md

Powershell创建的文件打开乱码

如果在 Powershell 中使用 echo 创建文本文档，文件的编码是 UTF-16LE 不是 UTF-8
重新创建即可

预览

1
yarn docs:dev

终端提示 vite v4.1.4 dev server running at: 后即可访问 http://localhost:8080/ 查看预览

设置站点信息

创建配置文件 .vuepress/config.ts，填入下面的内容然后重新预览

1
2
3
4
5
6
7
import { defineUserConfig } from 'vuepress'

export default defineUserConfig({
  lang: 'zh-CN',
  title: '网站标题',
  description: "网站描述",
})

确认生效后，我们可以设置主题了

安装主题

手动安装

参考 vuepress-reco - github，选择手动安装的方法

1
yarn add vuepress-theme-reco@next

修改配置文件 config.ts 

1
2
3
4
5
6
7
8
9
10
// .vuepress/config.ts

import { defineUserConfig } from 'vuepress'
import { recoTheme } from 'vuepress-theme-reco'

export default defineUserConfig({
  theme: recoTheme({ 
    /* Option */ 
  })
})

然后重新执行 yarn docs:dev 进行预览

设置导航栏

导航栏的格式为下面的 navbar:[ ] 部分，加入到 config.ts 中的 theme 部分

1
2
3
4
5
6
7
export default defineUserConfig({
  theme: recoTheme({ 
      { text: '首页', link: '/' },
      { text: '笔记', link: '/note/'}
      { text: 'Github', link 'https://github.com'}
   }),
})

这是一个简单的导航，效果如图
Simple Navbar

通过嵌套写法，可以实现下拉菜单，比如下面的配置将实现一个下拉菜单

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  text: '配置',
  children: [
    { text: '主题配置', link: '/docs/theme/frontmatter' },
    { text: 'Markdown 扩展', link: '/docs/theme/custom-container' },
    { text: '高级',         
    children: [
      { text: '主题配置', link: '/docs/theme/frontmatter' },
      { text: 'Markdown 扩展', link: '/docs/theme/custom-container' },
      { text: '高级', link: '/docs/theme/custom-catalog-title' },
    ], },
  ],
},

Navbar Dropmenu

设置侧栏

主题可以自动设置左侧侧栏： 自动设置系列(Series)
但是我设置后一开始并未生效，研究一下发现，需要在与 .vuepress 同目录建立一个 docs 文件夹，其下的文档可以自动生成，而且父文件夹也不能是 docs。

然后在主题的配置文件中设置 autoSetSeries: true 即可

缺点是文档的链接都在 docs 路径下，例如 https://example.com/docs/xxx.html
但是自动设置省心一些。

手动设置同样是编辑配置文件 config.ts ，reco 主题中侧边栏使用的是 series: { } ，可以放在 navbar:[ ] 的下面。

不适用于VuePress的默认主题

示例代码

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
series: {
  '/note/': [
    {
      // 分组的名称
      text: '基础',
      // children: [] 内部填写文件名 .md 可以省略
      // 获取文章内第一个标题作为导航名称
      children: [ 'linux', 'git' ]
    },
    {
      text: '高级',
      children: [ 'powershell']
    }
  ]
}

上面这段代码，将在 https://your.site/note/ 下面，生成一个如图的侧边栏。
VuePress reco Sidebar

如果左侧出现文章的名称显示成了文档的路径，一般是因为嵌套子文件夹导致的，填写完整路径即可

以及要使用 # 或是 yaml 指定标题才会被自动获取

1
2
3
---
title: 页面标题
---

或是使用 Markdown 格式

1
# 页面标题

添加自定义样式

创建 .vuepress/styles/index.css 文件，然后在里面加入样式代码即可。

自用的样式

 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
/* 直角主义 */
code {
    border-radius: 2px !important;
}

.code-group {
    border-radius: 0 !important;
}

div[class*=language-]{
    border-radius: 0 !important;
}

.custom-container {
    border-radius: 0 !important;
}

/* 给图片加个边框 */
p > img {
    margin: 0 auto;
    border: 1px solid #dddddd15;;
    border-radius: 0 !important;
}
/* 选中文字背景 */
::selection {
    background-color: #FF69B475;
    color: #fff;
}

/* 右侧边栏宽度 */
.page-catalog-container {
    width: auto !important;
    min-width: 14em !important;
    max-width: 22em !important;
}

推送到 Github 并设置 Pages

  • main : 用于备份源文件
  • gh-pages : 用于生成 Pages 的分支，由 Github Actions 自动构建

创建仓库

首先在 Github 上添加好公钥，然后建立一个空白的仓库。

如果想使用 Github Pages，且以 https://<username>.github.com/ 直接访问，而不要在链接中带有 repo 名称
Repo 的名称应该设置为 <username>.github.io 的形式

否则链接为 https://<username>.github.com/<repo>/

设置 .gitignore

创建 .gitignore 文件后，加入下面的内容 

1
2
3
4
node_modules
dist
.temp
.cache

初始化本地仓库

1
2
3
4
5
6
7
git init

git add --all
git commit -m "Initial Commit" --all
git branch -M main

git remote add origin https://github.com/<username>/<repo>.git

推送

1
git push -u origin main

设置 Github Actions

运行 yarn docs:build 会在 .vuepress/dist 下生成静态网页文件。

部署就是把 dist 文件夹的内容推送到 gh-pages 分支

使用 Github Actions 则不需要我们自己构建，可以实现当我们把源文件推送到 main 分支后自动构建并推送到 gh-pages 分支

设置 workflows 权限

首先，需要修改 Github Actions 的权限，不然最后 PUSH 时会报错，提示权限问题。

1
fatal: unable to access 'https://github.com/<username>/<repo>.git/': The requested URL returned error: 403

前往 Repo 的 Settings > Action > General > Workflow permissions，设置为 Read and write permissions

Action Permission

创建 workflows 文件

需要创建 .github/workflows/build-pages.yml 文件

填入下面的代码

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
name: build-pages

on:
  # 每当 push 到 main 分支时触发部署
  push:
    branches: [main]
  # 手动触发部署
  workflow_dispatch:

jobs:
  docs:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3
        with:
          # “最近更新时间” 等 git 日志相关信息，需要拉取全部提交记录
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          # 选择要使用的 node 版本
          node-version: 18
          
      - name: Run install
        uses: borales/actions-yarn@v4
        with:
          cmd: install # will run `yarn install` command

      # 运行构建脚本
      - name: Build VuePress site
        run: yarn build

      # 查看 workflow 的文档来获取更多信息
      # @see https://github.com/crazy-max/ghaction-github-pages
      - name: Deploy to GitHub Pages
        uses: crazy-max/ghaction-github-pages@v3
        with:
          # 部署到 gh-pages 分支
          target_branch: gh-pages
          # 部署目录为 VuePress 的默认输出目录
          build_dir: md/.vuepress/dist
        env:
          # @see https://docs.github.com/cn/actions/reference/authentication-in-a-workflow#about-the-github_token-secret
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

然后使用 git 追踪该文件

1
2
3
git add .github/workflows/build-pages.yml

git commit -m "create build-pages.yml"

在推送(git push)后可以访问 Repo 顶部的 Actions 查看运行状态

运行成功后我们可以查看 Repo 多了一个 gh-pages 分支

设置 gh-pages 作为 Source

前往 Repo 的 Settings，点击 Pages， 将 Source 选择为 Deploy from a branch
在 Brach 中选择 gh-pages ，点击 save

Action Permission

在 Actions 可以查看 pages build and deployment 的运行状态，完成后即可访问

https://username.github.io

查看

添加自定义域名

设置域名解析

为域名添加一条下面的解析

  • 类型为 CNAME
  • 指向 <username>.github.io

如果使用的不是子域名， www 和 @ 要一起解析

Repo 添加文件

然后向 Github 的 Repo 内添加文件名为 CNAME 的文件，保证是大写

文件内容为所使用的域名

1
example.com

CNAME 文件应该存在于在 gh-pages 分支，所以要前往 .vuepress/public 目录下创建 CNAME 文件
否则每次自动执行 Github Actions 之后，设置中的自定义域名设置都会重置

使用 CNAME 则不需要手动前往 Settings 设置自定义域名，等待 Github Actions 执行完成之后即可访问域名查看

添加自定义域名

前往 Repo 的 Settings，在 Pages 的 Custom domain 中填写自定义域名。

点击 save 后，等待检查 DNS 生效就会保存成功。

保存成功后访问对应域名即可。

域名是放在 Cloudflare 解析的话，如果 Github 提示解析出错，可以先暂停 Cloudflare 的 CDN

升级

BETA -> rc.Release

1
2
yarn upgrade vuepress@next
yarn upgrade vuepress-theme-reco@next

Beta版本升级至rc.Release后出错

主题升级至 reco v2.0.0.rc.1 / vuepress v2.0.0-rc.0 后 无法显示文章

在主题配置 config.ts 里添加以下内容即可，图示

1
2
3
4
5
6
7
8
9
locales: {
      // 键名是该语言所属的子路径
      // 作为特例，默认语言可以使用 '/' 作为其路径。
      '/': {
        lang: 'zh-CN',
        title: 'VuePress',
        description: 'Vue 驱动的静态网站生成器',
      },
    },