笔记：关于使用vitepress 制作静态站点并托管到 gitee

笔记：关于使用vitepress 制作静态站点并托管到giteegitee

1. 概述

静态页面生成

我们都希望拥有自己的个人网站，但是由于很多人不懂技术，使得制作网站有很高的门槛和成本。但是如今，哪怕你是小白——完全不懂编程，也可以通过 vitepress 帮助我们快速地生成我们的个人站点。VitePress 是一个静态站点生成器 （SSG），旨在构建快速、以内容为中心的网站，它可以获取用 Markdown 编写的源内容，为其应用主题，并生成可以轻松部署到任何地方的静态 HTML 页面。

代码托管

哦，对了！你可能还不知道如何才能将你的个人网站部署到公网上，又或者是不想购买自己的服务器——笔记服务器的成本是比较高昂的，即使你购买了云服务器，如阿里云、腾讯云、华为云。但是如果你只是想发布自己的个人博客，或者一些简单的信息的站点的话，都是很不划算的，这时你可以考虑使用免费的 Gitee Pages 进行托管。

关于本文

本文从零开始手把手的教你如何使用本文从零开始手把手的教你如何使用 vitpress 制作自己的个人网站，并将其托管到 Gitee Pages 上面。

2. vitpress 初步

2.1 准备工作

安装 NodeJS。如果你的 Windows 电脑上有安装 choco 包管理器，可以再 powershell/命令行工具 中通过命令安装：

choco install nodejs

当然也可以去官网下载安装包：

https://nodejs.org/en/

2.2 项目创建 与 目录结构

现在新建一个文件夹，并在该文件夹内运行项目初始化命令：

npm init -y

得到了一个新项目，它将用于放置我们制作的静态网站及其所用资料。

在该文件夹内运行以下命令：

npm install -D vitepress
# 或者使用 pnpm
pnpm i -D vitepress

表示安装 vitepress 作为开发依赖。

接着我们执行 vitepress 初始化，使这个项目成为一个 vitepress 项目：

npx vitepress init
# 或者使用 pnpm
pnpm exec vitepress init

2.3 vitpress 命令

2.3.1 运行开发服务器

如果全局安装 vitepress ，可以使用 vitepress dev 运行开发服务：

vitepress dev

仅在当前项目安装时，需要使用 npx 或者 pnpm exec 运行，以寻找当前项目模块的 ./bin 目录：

npx vitepress dev
#或者
pnpm exec vitepress dev

成功运行后可以在浏览器中访问由 cli 默认初始化出来的 vitepress 站点：

2.3.2 构建静态站点

vitepress build

同理，若在当前项目安装 vitepress 时运行：

npx vitepress build
#或者
pnpm exec vitepress build

2.4 配置脚本运行字段

Note 最新版本的 vitepress 自带的 cli 可以帮我们完成这一节的工作，只需要你运行 vitepress 初始化命令时选上此项：

还记得我们使用命令“npm init -y”（或者“pnpm init”）初始化项目吗，如果你仔细观察会发现项目下下面生成了一个名为 pacakage.json 的文件。这个文件是一个用于记录项目配置信息的本文文件。

我们在该文件的scripts字段下添加以下子键值对，其中键表示命令名、值表示命令对应的内容：

{
  // ...已省略该文件的其它内容
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  },
}

这样我们就可以使用 npm run 命令名的方式快速执行相应的命令了。比如：

npm run docs:dev

相当于在项目中执行：

vitepress dev docs

依此类推。

2.5 路由

2.5.1 什么是路由

对于完全不了解技术的小白，有必要介绍一下路由的概念。

故名思意，路由就是路径上哪儿。简单说来路由表示的是不同网页的访问地址，就像现实生活表示一户人家、一个机构、一家公司。

路由 一词的来源与其实工程技术并无关系，它很早就有，仅仅是一个生活中很常见的词汇，含以上表示来自哪里。随着二十世纪电气的到来，电气电子相关技术的蓬勃发展，控制技术、通信工程等相关专业应运而生。不论是从最早在电气控制领域的 工业控制网络 到后来的 计算机网络，随着生产力发展的需要都引入了很多来源于生活的概念，路由 就是其中之一。在网络工程领域，路由（routing）是指分组从源到目的地时，决定端到端路径的网络范围的进程。后来随着互联网技术的发展，从网络工程领域再次借用和引申了 路由 这一概念。在用户界面系统中，比如我们所熟知的 web，路由简单的来说就是根据用户请求的 URL 链接来判断对应的处理程序，并返回处理结果。¹

2.5.2 VitePress 的路由原理

与编程项目中复杂的路由系统不一样，VitePress 中提供了所谓 基于文件的路由（File-Based Routing）。

这就是说， VitePress 生成的 HTML 页面是从源 Markdown 文件的目录结构映射的。

举个例子来说明，给定以下目录结构：

.
├─ guide
│  ├─ getting-started.md
│  └─ index.md
├─ index.md
└─ prologue.md

这在使用 build 后对应成相应目录结构的的 html：

index.md                  -->  /index.html (accessible as /)
prologue.md               -->  /prologue.html
guide/index.md            -->  /guide/index.html (accessible as /guide/)
guide/getting-started.md  -->  /guide/getting-started.html

要能够正确 build 得到你想要的 html，则需要搞清楚两个概念，分别是：

根目录 和 源目录

2.5.2.1 根目录

项目根目录 是 VitePress 将尝试查找特殊目录的地方。该目录是 VitePress 配置文件、开发服务器缓存、构建输出 和 可选主题自定义代码 的保留位置。

当运行vitepress dev或从vitepress build命令行运行时，VitePress 将使用当前工作目录作为项目根目录。要将子目录指定为 root，您需要将相对路径传递给命令。例如，如果您的 VitePress 项目位于./docs中，则应运行：

vitepress dev docs

2.5.2.2 源目录

源目录 是 Markdown 源文件 所在的位置。

默认情况下，它与项目根目录相同。

但是，你也可以通过 srcDir（该选项的默认值为.，即根目录） 配置选项对其进行配置：

export default {
  srcDir: './src'
}

2.5.3 页面之间的链接

在页面之间链接时，可以同时使用绝对路径和相对路径。请注意，尽管.md和.html扩展名都可以使用，但最佳做法是省略文件扩展名，以便 VitePress 可以根据您的配置生成最终 URL。

<!-- Do -->
[Getting Started](./getting-started)
[Getting Started](../guide/getting-started)
<!-- Don't -->
[Getting Started](./getting-started.md)
[Getting Started](./getting-started.html)

2.5.4 动态路由

3. vitpress 配置

在 .vitepress 目录下的 config.js 文件是 vitpress 的配置文件。vitpress 配置 实际上就是定义一些选项。看起来就像这样：

// .vitepress/config.js
export default {
  // 站点级选项（站点配置）
  title: 'VitePress',
  description: 'Just playing around.',
  themeConfig: {
    // 主题级选项（主题配置）
  }
}

依据其作用层级，分为 站点配置 、 页面配置 和 主题配置 三部分：

• 站点配置（Site config） 用于 定义站点的全局设置的位置。
  相关应用程序配置选项用于定义适用于每个 VitePress 站点的设置，无论它使用什么主题。例如，网站的基目录或标题。
• 页面配置（Frontmatter config）支持基于页面的配置。在每个 markdown 文件中，您可以使用前言配置来 覆盖 站点级 或 主题级 配置选项。此外，还有一些只能在前言中定义的配置选项。页面配置是一个 YAML 格式的段落快，它写在
• 主题配置 可自定义界面风格。通过配置文件中的选项定义主题配置，就可以修改所使用地主题。

3.1 站点配置

站点配置是 Vitepress 的全局配置，用于配置整个站点的一些基本信息。你可以在项目的根目录下创建一个 .vitepress/config.js 文件来配置站点信息。以下是一些常用的站点配置选项：

例如：

// .vitepress/config.js
module.exports = {
  title: 'My Vitepress Site',
  description: 'A simple Vitepress site',
  head: [
    ['link', { rel: 'icon', href: '/favicon.ico' }]
  ],
  themeConfig: {
    // ... 主题配置
  }
}

例如：

---
title: My Page
description: A simple page
layout: custom-layout
head:
  - ['link', { rel: 'icon', href: '/favicon.ico' }]
---
# My Page
This is a simple page with custom layout.

3.2 页面配置

页面配置用于配置单个页面的信息，例如页面标题、描述等。你可以在每个 Markdown 文件的开头使用 YAML front matter 进行配置。以下是一些常用的页面配置选项：

3.3 主题配置

主题配置用于配置 Vitepress 主题的一些选项，例如导航栏、侧边栏等。主题配置应该在站点配置的 themeConfig 选项中进行配置。以下是一些常用的主题配置选项：

例如：

// .vitepress/config.js
module.exports = {
  // ... 站点配置
  themeConfig: {
    navbar: [
      { text: 'Home', link: '/' },
      { text: 'Guide', link: '/guide/' },
      { text: 'External', link: 'https://google.com' },
    ],
    sidebar: {
      '/guide/': [
        { text: 'Introduction', link: '/guide/introduction' },
        { text: 'Getting Started', link: '/guide/getting-started' },
      ],
    },
    repo: 'https://github.com/your/repo',
    editLinks: true,
    lastUpdated: 'Last Updated',
  }
}

4. 创作你的内容吧！

4.1 Markdown 简介

不论是 数据科学家、程序员还是网络作家，掌握 Markdown 就像一个普通办公室工作人员掌握 office word 或者 wps word 那样重要——如今你看到的公众号、博客等等大多数都是使用 MarkDown完成的。

标题语法

# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题

文本样式

*强调文本* _强调文本_
**加粗文本** __加粗文本__
==标记文本==
~~删除文本~~
> 引用文本
H~2~O is是液体。
2^10^ 运算结果是 1024。

列表语法

项目
  * 项目
    + 项目
1. 项目1
2. 项目2
3. 项目3
- [ ] 计划任务
- [x] 完成任务

效果如下：

项目

• 项目

• 项目

1. 项目1
2. 项目2
3. 项目3

• 计划任务
• 完成任务

表格语法

| title1 | title2 | title3 |
|:-|-:|:-:|
| 左对齐 | 右对齐 | 居中对齐 |

效果如下：

其中：

• 居中对齐时可以省略冒号 : 不写；
• 最左和最右两侧的竖线 | 可以省略不写。

如：

title1 | title2 | title3
:-|-:|-
左对齐 | 右对齐 | 居中对齐

数学公式

你可以使用 $$表示一个公式块的开头和结束，在其中编辑 mathJax/ katex 公式

$$
c = a^2 + b^2 \\
\Gamma(z) = \int_0^\infty t^{z-1}e^{-t}dt\,.
$$

c = a 2 + b 2 Γ ( z ) = ∫ 0 ∞ t z − 1 e − t d t   . c = a^2 + b^2 \\ \Gamma(z) = \int_0^\infty t^{z-1}e^{-t}dt\,.c=a2+b2Γ(z)=∫0∞tz−1e−tdt.

你可以写多个公式、每个公式占用一行，\\ 表示公式之间的换行。

4.2 vitepress 中的 Markdown 语法

VitePress 带有内置的 Markdown 扩展，这个扩展用于增加一些特定的 Markdown 语法。

输入

::: info
This is an info box.
:::
::: tip
This is a tip.
:::
::: warning
This is a warning.
:::
::: danger
This is a dangerous warning.
:::
::: details
This is a details block.
:::

输出

::: info
This is an info box.
:::
::: tip
This is a tip.
:::
::: warning
This is a warning.
:::
::: danger
This is a dangerous warning.
:::
::: details
This is a details block.
:::

4.3 vitepress 中的 使用 Vue

要在 vitpress 项目中使用 vue 我们首先要在项目下安装vue作为依赖，就像一开始的时候我们安装 vitpress 那样：

npm install vue
# 或 如果你用 pnpm
pnpm i vue

在 VitePress 中，每个 Markdown 文件都被编译成 HTML，然后作为 Vue 单文件组件进行处理。这意味着你可以在 Markdown 中使用任何 Vue 功能，包括动态模板、使用 Vue 组件或通过添加 <script> 标签来任意页面内 Vue 组件逻辑。

5. Gitee Pages

5.1 Gitee Pages 相关概念与原理

和 Github Pages 一样，Gitee Pages 是一个免费的静态网页托管服务，您可以使用 Gitee Pages 托管博客、项目官网等静态网页，可以看作 Github Pages 的国内版。

Gitee Pages 是面向 Gitee 用户开放的静态页面搭建托管服务，用户可以通过默认提供的域名 gitee.io 来发布自己的站点，它支持除了原始的HTML，支持Jekyll、Hugo、Hexo 等静态网站生成引擎，可以很方便的在线编译这几类静态站点项目。我们这里使用的是 vitpress 打包构建之后的原生 html 进行托管。

Gitee Pages 分为免费版和付费版，我们这里所使用的是其免费版本。付费版 称之为 Gitee Pages Pro 拥有更多地针对于企业级地功能，如 自定义域名、支持发布 仓库中 某个目录（ 例如你可以将仓库的文档目录 doc 发布成静态网页 ）等等。

5.2 网站托管到 Gitee Pages 的基本步骤概述

当将网站托管到Gitee Pages时，可以按照以下章节进行操作：

5.2.1 创建Gitee仓库

在Gitee上创建一个新的仓库，用于托管您的网站。确保仓库名称与您的用户名或项目相关联，这样Gitee Pages将能够自动识别您的网站。

5.2.2 上传网站文件

将网站文件上传到新创建的Gitee仓库。这些文件可以是HTML、CSS、JavaScript和其他相关资源。

5.2.3 配置Gitee Pages

1. 进入Gitee仓库页面，点击"Settings"（设置）选项卡。
2. 向下滚动并找到"GitHub Pages"部分。
3. 在"Source"（源）下拉菜单中选择您希望托管的分支，通常是"master"分支。
4. 输入您的网站文件存放在仓库中的路径，通常是根目录(“/”)。
5. 点击"Save"（保存）按钮保存配置。

5.2.4 启用Gitee Pages

1. 在Gitee仓库页面的"Settings"（设置）选项卡中，向下滚动到"GitHub Pages"部分。
2. 点击"Enable"（启用）按钮。
3. Gitee Pages会为您的仓库生成一个网址，显示在"GitHub Pages"部分。
4. 点击生成的网址即可访问您的网站。

5.2.5 自定义域名（非必须）

1. 如果您拥有自己的域名，可以将其与Gitee Pages配对，以使用自定义域名访问您的网站。
2. 在Gitee仓库页面的"Settings"（设置）选项卡中，向下滚动到"Custom Domain"（自定义域名）部分。
3. 输入您的自定义域名，并点击"Save"（保存）按钮。
4. 根据Gitee提供的指示，在您的域名注册商那里配置域名解析，将域名指向Gitee Pages提供的IP地址。

通过按照以上章节的步骤，您就可以将您的网站成功托管到Gitee Pages上，并通过生成的网址或自定义域名来访问您的网站。

5.3 托管前的准备

进入 gitee（码云）登陆页面 https://gitee.com/login，如果你此时还未注册 gitee 账号请依据页面上的提示自行进行注册，如果已经注册，请直接登录：

登陆后点击右上角的头像，点击“个人主页”，就可以进入你的 gitee 主页了。

5.4 从新建仓库开始

在 gitee 和 github 中仓库是用来存储文件地，对于程序开发者来说主要是用来存储我们的代码，这里我们用它来存储 使用 vitepress 构建好的个人网站相关文件。

点击 gitee 页面右上角的 + 号，在下拉菜单中选择新建仓库。

填写仓库信息：

我们只有将项目设置为开源才能让别人访问到我们的站点。但是由于 22 年以后，gitee 审核机制要求所带来的限制，让我们无法在创建项目时直接创建公开的仓库，如需创建公开仓库只能在创建仓库后通过 “仓库设置” 中修改为公开。创建完成后你会看到这样的界面：

现在我们还没有上传文件，如果我们点击 “初始化 readme” 文件就会自动生成两个本文文件，这样你会看到向文件夹一样的结构（虽然这不是必须的）：

现在你需要知道的是如何获取你的这个新建项目的仓库地址，这在我们之后使用 git 工具进行提交静态页面代码时都需要使用到。

• 如果没有任何文件，你可以直接复制下图区域的地址：
  
• 如果初始化readme文件、或者上传又其它文件，可以点击代码区右上角的 “克隆/下载” ，然后复制下拉内容中的url：
  

5.5 使用 git 工具

5.5.1 安装 git 工具

1. 在 Linux 上安装 git

Linux 上用二进制安装程序来安装基本的 Git 工具，可以使用发行版包含的基础软件包管理工具来安装。 例如基于 Debian 的发行版上（如 ubuntu）可以使用

sudo apt install git-all

Fedora 或与之紧密相关的基于 RPM 的发行版（如如 RHEL 或 CentOS）你可以使用 dnf：

sudo apt install git-all

2. 在 Windows 上安装 git

在 Windows 上可以通过以下方式下载对应于你系统的版本安装：

或者使用 Choco 包管理工具（请参考博文《Windows中使用包管理器（类似于apt/yum的） - Chocolatey》）

choco install git

以及 winget 工具。（需要安装 winget 工具）打开 powershell 输入：

winget install --id Git.Git -e --source winget

3. 在 macOS 上安装 git

在 Mac 上安装 Git 最简单的方法是安装 Xcode Command Line Tools，在 Terminal 里尝试首次运行 git 命令即可：

git --version

如果没有安装过命令行开发者工具，将会提示你安装。

附：

f1. 使用https部署的补充：申请一个 SSH 证书

使用 HTTPS 协议需要一个SSH 证书。关于什么是 https、ssh，感兴趣的读者可以参考我的另外一篇博客《用户认证、权限、安全》。

作为一个个人站点而言，我们可以通过Freessl 获取免费 SSL 服务，这个品牌似乎也是 和码云（gitee）同一家哦那公司旗下的产品。

在这里输入你的域名，点击 创建免费的SSL证书，跳转到登陆页面，单独进行注册并登陆：

ACME 域名配置

登陆后进行 ACME 域名配置。先会校验你的域名，填写你的域名值，紧接着是 DCV 配置，它会更具你填写的路由进行检测。

如果你 不适用托管，而是将站点是部署在你个人的服务器上，你需要登陆你的域名解析服务提供商的控制台，如 万网（阿里云）、腾讯云、华为云等等，在 DSN解析处配置你的域名。即 选择“添加记录”，将上述主机记录、记录类型（CNAME）、记录值填入，并确定使之生效。

修改完成之后意味着你的记录类型为 CNAME，记录值不再是以前的ipv4那样的地址。看起来就像这样：

配置完成后需要一点时间等待更改，直到所有解析均校验通过：

安装acme.sh

curl https://get.acme.sh | sh -s email=my@example.com

如果上面官方下载地址失败 或者 太慢，可以选用国内的备用地址

curl https://gitcode.net/cert/cn-acme.sh/-/raw/master/install.sh?inline=false | sh -s email=my@example.com

注意：安装完成后，再重新打开命令行（如果是 SSH，选择重新连接），以使acme.sh命令生效。如果实在不能生效则手动进入 /root/.acme.sh

cd /root/.acme.sh

也可以从github clone一下代码：

git clone https://github.com/acmesh-official/acme.sh.git

进入文件夹

cd acme.sh

然后运行部署命令(注意替换掉xxxxxxxxxxxxxx)

sh acme.sh --issue -d thispage.tech  --dns dns_dp --server https://acme.freessl.cn/v2/DV90/directory/xxxxxxxxxxxxxx

部署到 WebServer（使用Nginx）

例如

sh acme.sh --install-cert -d example.com \
--key-file       /path/to/keyfile/in/nginx/key.pem  \
--fullchain-file /path/to/fullchain/nginx/cert.pem \
--reloadcmd     "service nginx force-reload"

注

部署过程可能会需要不断重试

1. 参考博客《为koa项目添加路由模块》：https://blog.csdn.net/qq_28550263/article/details/129828590↩︎