构建VitePress文档站

VitePress#

VitePress是一个由Vue构建的文档网站，相比于Hexo和Hugo这样的博客，每个主题都有自己独特风格的样式，写法也有很大的差别。VitePress的Markdown文档写法简单，也会更注重文档中最重要的文字表达。

安装VitePress#

点击打开VitePress官网安装介绍

安装Node.js后，按照官网提示进行安装与部署配置即可完成网站的搭建

VitePress配置文件与配置#

目录结构#

安装完成之后进入网站目录，大致是如下的结构

配置文件#

配置文件位于/.vitepress/目录下，配置文件名字是config.mjs，页面的配置在里面调整。网站默认语言是中文，调整页面的默认语言也在这个文件中。

更换网站默认语言#

点击打开vitepress-i18n项目文档

根据这个项目，提示我们先安装一下这个插件

1
npm i -D vitepress-i18n

在配置文件中更改配置格式，并应用这个插件

这是配置文件默认的样式

1
import { defineConfig } from "vitepress";
2

3
// https://vitepress.dev/reference/site-config
4
export default defineConfig({
5
    srcDir: "docs",
6
    publicDir: ".vitepress/public",
7
    title: "Inkwell Ops",
8
    description: "Linux & Infrastructure",
9
    themeConfig: {
10
        // https://vitepress.dev/reference/default-theme-config
11
        nav: [
12
            { text: "Home", link: "/" },
13
            { text: "Blog", link: "https://ivoink.qzz.io", target: "_blank" },
14
        ],
15

16
        sidebar: [
17
            {
18
                text: "Examples",
19
                items: [
20
                    { text: "Markdown Examples", link: "/markdown-examples" },
21
                    { text: "Runtime API Examples", link: "/api-examples" },
22
                ],
23
            },
24
            {
25
                text: "Linux",
26
                base: "/linux-system/",
27
                items: [{ text: "Overview", link: "/" }],
28
            },
29
        ],
30

31
        // socialLinks: [
32
        //     { icon: "github", link: "https://github.com/vuejs/vitepress" },
33
        // ],
34
    },
35
});

我们需要改成官网的这种格式

1
import { withI18n } from 'vitepress-i18n';
2

3
const vitePressOptions = {
4
  title: 'VitePress',
5
  themeConfig: {
6
    // ...
7
  }
8
};
9

10
const vitePressI18nOptions = {
11
  locales: ['en', 'ko', 'zhHans']
12
};
13

14
export default defineConfig(withI18n(vitePressOptions, vitePressI18nOptions));

可以理解成为我们需要将原来在default配置里面的放入vitePressOptions这个const变量当中

1
import { defineConfig } from "vitepress";
2
import { withI18n } from "vitepress-i18n";
3

4
// https://vitepress.dev/reference/site-config
5
const vitePressOptions = {
6
    srcDir: "docs",
7
    publicDir: ".vitepress/public",
8
    title: "Inkwell Ops",
9
    description: "Linux & Infrastructure",
10
    themeConfig: {
11
        // https://vitepress.dev/reference/default-theme-config
12
        nav: [
13
            { text: "Home", link: "/" },
14
            { text: "Blog", link: "https://ivoink.qzz.io", target: "_blank" },
15
        ],
16

17
        sidebar: [
18
            // {
19
            //     text: "Examples",
20
            //     items: [
21
            //         { text: "Markdown Examples", link: "/markdown-examples" },
22
            //         { text: "Runtime API Examples", link: "/api-examples" },
23
            //     ],
24
            // },
25
            {
26
                text: "关于",
27
                items: [{ text: "关于站点", link: "/about" }],
28
            },
29
            {
30
                text: "Linux",
31
                base: "/linux-system/",
32
                items: [
33
                    { text: "Overview", link: "/" },
34
                    {
35
                        text: "01 - Linux 安装与远程登录",
36
                        link: "/01-linux-installation-and-remote-login",
37
                    },
38
                    {
39
                        text: "02 - 软件与软件源",
40
                        link: "/02-software-and-software-sources",
41
                    },
42
                ],
43
            },
44
        ],
45

46
        // socialLinks: [
47
        //     { icon: "github", link: "https://github.com/vuejs/vitepress" },
48
        // ],
49
    },
50
};
51

52
const vitePressI18nOptions = {
53
    locales: ["zhHans"],
54
};
55

56
export default defineConfig(withI18n(vitePressOptions, vitePressI18nOptions));

favicon#

这里推荐一个制作favicon的网站

点击跳转Favicon.pub

在其中生成之后的照片几乎有了所有设备需要的格式

我们需要将其放在public目录当中，至于怎么确定public目录在生成之后里面的文件是否会出现在根目录也十分简单，输入

1
npm run docs:build

这个时候会在/.vitepress/目录下出现一个dist目录，里面便是这个博客整个网站目录

我的图片已经出现在根目录当中，我的public文件夹在docs，也就是文档目录当中

favicon的配置#

参考我的配置的head部分

1
import { defineConfig } from "vitepress";
2
import { withI18n } from "vitepress-i18n";
3

4
// https://vitepress.dev/reference/site-config
5
const vitePressOptions = {
6
    srcDir: "docs",
7
    publicDir: ".vitepress/public",
8
    head: [
9
        ["link", { rel: "icon", type: "image/svg+xml", href: "/favicon.svg" }],
10
        [
11
            "link",
12
            {
13
                rel: "icon",
14
                type: "image/png",
15
                sizes: "16x16",
16
                href: "/favicon-16x16.png",
17
            },
18
        ],
19
        [
20
            "link",
21
            {
22
                rel: "icon",
23
                type: "image/png",
24
                sizes: "32x32",
25
                href: "/favicon-32x32.png",
26
            },
27
        ],
28
        [
29
            "link",
30
            {
31
                rel: "icon",
32
                type: "image/png",
33
                sizes: "48x48",
34
                href: "/favicon-48x48.png",
35
            },
36
        ],
37
        [
38
            "link",
39
            {
40
                rel: "apple-touch-icon",
41
                sizes: "180x180",
42
                href: "/apple-touch-icon.png",
43
            },
44
        ],
45
        [
46
            "link",
47
            {
48
                rel: "apple-touch-icon",
49
                sizes: "152x152",
50
                href: "/apple-touch-icon-152x152.png",
51
            },
52
        ],
53
        [
54
            "link",
55
            {
56
                rel: "apple-touch-icon",
57
                sizes: "167x167",
58
                href: "/apple-touch-icon-167x167.png",
59
            },
60
        ],
61
        ["link", { rel: "manifest", href: "/site.webmanifest" }],
62
        ["meta", { name: "theme-color", content: "#ffffff" }],
63
        [
64
            "meta",
65
            { name: "msapplication-config", content: "/browserconfig.xml" },
66
        ],
67
    ],
68
    title: "Inkwell Ops",
69
    description: "Linux & Infrastructure",
70
    themeConfig: {
71
        // https://vitepress.dev/reference/default-theme-config
72
        nav: [
73
            { text: "Home", link: "/" },
74
            { text: "Blog", link: "https://ivoink.qzz.io", target: "_blank" },
75
        ],
76

77
        sidebar: [
78
            // {
79
            //     text: "Examples",
80
            //     items: [
81
            //         { text: "Markdown Examples", link: "/markdown-examples" },
82
            //         { text: "Runtime API Examples", link: "/api-examples" },
83
            //     ],
84
            // },
85
            {
86
                text: "关于",
87
                items: [{ text: "关于站点", link: "/about" }],
88
            },
89
            {
90
                text: "Linux",
91
                base: "/linux-system/",
92
                items: [
93
                    { text: "Overview", link: "/" },
94
                    {
95
                        text: "01 - Linux 安装与远程登录",
96
                        link: "/01-linux-installation-and-remote-login",
97
                    },
98
                    {
99
                        text: "02 - 软件与软件源",
100
                        link: "/02-software-and-software-sources",
101
                    },
102
                ],
103
            },
104
        ],
105

106
        // socialLinks: [
107
        //     { icon: "github", link: "https://github.com/vuejs/vitepress" },
108
        // ],
109
    },
110
};
111

112
const vitePressI18nOptions = {
113
    locales: ["zhHans"],
114
};
115

116
export default defineConfig(withI18n(vitePressOptions, vitePressI18nOptions));

预览#

我现在是在我开发机上面搭建并且去编写的，所以我不可能去使用127.0.0.1这样的回环地址去预览，这个时候就要去动一下package.json这个配置文件，可以看一下docs:dev的更改

1
{
2
    "devDependencies": {
3
        "vitepress": "^2.0.0-alpha.17",
4
        "vitepress-i18n": "^1.3.5"
5
    },
6
    "scripts": {
7
        "docs:dev": "vitepress dev --host 0.0.0.0",
8
        "docs:build": "vitepress build",
9
        "docs:preview": "vitepress preview --host 0.0.0.0"
10
    }
11
}

部署#

我使用的是GitHub Pages去实现的静态网页，新建目录/.github/workflow在里面新建deploy.yml文件，直接使用我的就可以

1
name: Deploy GitHub Pages
2

3
on:
4
  push:
5
    branches: [main]
6
  workflow_dispatch:
7

8
permissions:
9
  contents: read
10
  pages: write
11
  id-token: write
12

13
concurrency:
14
  group: pages
15
  cancel-in-progress: false
16

17
jobs:
18
  build:
19
    runs-on: ubuntu-latest
20
    steps:
21
      - name: Checkout
22
        uses: actions/checkout@v4
23
        with:
24
          fetch-depth: 0
25

26
      - name: Setup Node
27
        uses: actions/setup-node@v4
28
        with:
29
          node-version: 20
30
          cache: npm
31

32
      - name: Install dependencies
33
        run: npm ci
34

35
      - name: Build
36
        run: npm run docs:build
37

38
      - name: Upload artifact
39
        uses: actions/upload-pages-artifact@v3
40
        with:
41
          path: .vitepress/dist
42

43
  deploy:
44
    needs: build
45
    runs-on: ubuntu-latest
46
    environment:
47
      name: github-pages
48
      url: ${{ steps.deployment.outputs.page_url }}
49
    steps:
50
      - name: Deploy
51
        id: deployment
52
        uses: actions/deploy-pages@v4

使用这个工作流，在仓库里面需要做下面这个更改，将Pages的Source改成GitHub Actions即可

如果有自己的域名，一定要记得写CNAME文件在public文件夹内