Vuepress、Vitepress 框架

介绍

使用

快速搭建

  • Vuepress 框架快速搭建
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
mkdir vuepress-demo && cd $_

yarn init  # 初始化项目

# 添加 scripts

# 安装 reco 主题
# 可以不安装主题，其余设置均一样
yarn add vuepress-theme-reco --dev

mkdir docs
echo '# Hello VuePress' > docs/README.md

# yarn 可替换成 pnpm、npm run
yarn docs:dev    # 本地预览
yarn docs:build  # 构建

# 若 build 时报错
# 通常是由于 Node.js 版本与 crypto 模块的兼容性问题引起的
# 方式 1 添加环境变量
export NODE_OPTIONS=--openssl-legacy-provider
# 方式 2  修改 package.json 中的 build 参数值
"docs:build": "NODE_OPTIONS=--openssl-legacy-provider vuepress build docs"
  • 在 package.json 中添加 scripts 参数
1
2
3
4
5
6
{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}
  • Vitepress 框架快速搭建
1
2
3
4
5
6
7
8
9
10
mkdir vitepress-demo && cd $_

# npm 可替换成 yarn、pnpm
npm add -D vitepress

npx vitepress init    # 初始化 

npm run docs:dev      # 本地预览
npm run docs:build    # 构建
npm run docs:preview  # 构建后预览
  • 目录结构
1
2
3
4
5
├── docs/
│   ├── .vuepress/      # .vitepress/
│   │   ├── config.js   # 配置文件 config.mjs
│   └── README.md
├── package.json

部署

  • GitHub Actions 示例（Vitepress 框架部署时只需将 .vuepress 修改为 .vitepress）
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
name: Vuepress Depoly

on:
  push:
    branches: [main]

permissions:
  contents: write

jobs:
  docs:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: latest
          cache: yarn

      - name: Install dependencies
        run: yarn
      - name: Build VuePress site
        run: yarn docs:build

      - name: Deploy to GitHub Pages
        uses: crazy-max/ghaction-github-pages@v4
        with:
          target_branch: gh-pages
          build_dir: docs/.vuepress/dist
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

配置

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
47
48
49
50
module.exports = {
  title: 'xxx',  // 网站标题
  description: 'xxx',  // 网站描述
  base: '/repo-name/',  // 通常为 GitHub repo name

  // 主题配置
  themeConfig: {

    // 在页面下方添加最后更新时间
    lastUpdated: 'Last Updated',

    // 搜索
    search: true,
    searchMaxSuggestions: 10,

    // 导航栏
    navbar: [
      // 普通导航栏
      { text: '首页', link: '/' },
      { text: '指南', link: '/guide/' },
      // 下拉菜单导航栏
      {
        text: '更多',
        children: [
          { text: '项目', link: '/projects/' },
          { text: '关于', link: '/about/' },
        ],
      },
    ],

    // docs 侧边栏配置 含多级子目录示例
    sidebar:[
        {
            title: '科研工具',
            path: '/scitoolkits/',
            collapsable: false,
            children: [
                {title: 'LAMMPS 安装', path: 'scitoolkits/lammps-install'},
                {
                    title: 'atomate',
                    path: 'scitoolkits/atomate/',
                    collapsable: false,
                    children: [
                        {title: 'atomate 安装与使用', path: 'scitoolkits/atomate/atomate-usage'},
                    ]
                },
    ],
    ...
  }
}
  • Vitepress 框架配置（配置文件：docs/.vitepress/config.js）：
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
47
48
49
50
51
52
53
import { defineConfig } from 'vitepress'

// https://vitepress.dev/reference/site-config
export default defineConfig({
  title: "xxx",
  description: "xx",
  base: '/repo-name/',

  themeConfig: {
    // https://vitepress.dev/reference/default-theme-config

    docFooter: {
      prev: '上一页',
      next: '下一页'
    },

    footer: {
      message: '基于 MIT 许可发布',
      copyright: `版权所有 © 2024-${new Date().getFullYear()}`
    },

    lastUpdated: {
      text: '最后更新于',
      formatOptions: {
        dateStyle: 'short',
        timeStyle: 'medium'
      }
    },

    // 导航栏
    nav: [
      { text: '首页', link: '/' },
      { text: '笔记', link: 'scitoolkits/lammps-install' }
    ],

    // docs 侧边栏配置 含多级子目录示例
    sidebar: [
      {
        text: '科研工具',
        collapsed: false,
        items: [
            {text: 'LAMMPS 安装', link: 'scitoolkits/lammps-install'},
            {   
                text: 'atomate',
                collapsed: false,
                items: [
                    {text: 'atomate 安装与使用', link: 'scitoolkits/atomate/atomate-usage'},
                ]
            },
    ],
    ...
  }
}

  • Vitepress 与 Vuepress 框架中 sidebar 参数配置差异

    • text - title, collapsed - collapsable, items - children, link - path
    • 多级子目录下，Vitepress 框架下不能有 index.md 文件，而 Vuepress 框架允许有

  • reco v1.x 版本配置参考：Vuepress-theme-reco-v1.x 新手指北之Hello烤鸭 | latte and cat

  • reco v1.x 版本常用参数设置：

    • 有分类、标签和时间轴功能，因此可不用设置 docs 子目录的导航栏
    • 会预设一些插件（如 一键从页面底部到顶部）
    • md 文档的目录侧边栏可自动生成，docs 的侧边栏仍需手动生成，较繁琐
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
// 移动端优化
head: [
  ['meta', { name: 'viewport', content: 'width=device-width,initial-scale=1,user-scalable=no' }]
],

themeConfig: {

 // md 文档目录侧边栏 右侧
  subSidebar: 'auto',
  sidebarDepth: 5,

  startYear: '2024',

  // 关闭 404 页面腾讯公益
  noFoundPageByTencent: false,

  type: 'blog',

  blogConfig: {
      category: {
        location: 2, // 在导航栏菜单中所占的位置，默认 2
        text: '分类' // 默认文案 “分类”
      },
      tag: {
        location: 3, // 在导航栏菜单中所占的位置，默认 3
        text: '标签' // 默认文案 “标签”
      }
  },

  nav: [
    // 添加时间轴和 GitHub 链接
    { text: '时间轴', link: '/timeline/', icon: 'reco-date' },
    { text: 'GitHub', link: 'https://github.com/username', icon: 'reco-github' }
  ],

}

搜索功能

Vuepress 和 Vitepress 框架均支持使用 Algolia DocSearch 搜索文档站点

1
2
3
4
5
6
7
8
9
10
11
12
// docs/.vuepress/config.js
module.exports = {
  themeConfig: {
    // ...
    algolia: {
      appId: 'XXX',
      apiKey: 'XXX',
      indexName: 'XXX'
    },
    // ...
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// docs/.vitepress/config.js
export default defineConfig({
  themeConfig: {
    // ...
    search: {
      provider: 'algolia',
      options: {
        appId: '...',
        apiKey: '...',
        indexName: '...'
      }
    },
    // ...
  }
})