建立你自己的站点

你是否希望：

• 将自己的 Markdown 文档转化为网页，在任意联网设备上访问？
• 自动生成美观的网页，包括渲染复杂数学公式？
• 利用 GitHub 等代码托管平台，无忧地保存你的文档各个版本，免去备份之忧？
• 不使用复杂且昂贵的 $\text{IaaS}$ 云服务，不用担心服务器的安全性、稳定性、维护成本等问题？
• 建立一个近乎免费的个人静态站点，用来存放笔记或搭建博客？

如果你的答案是肯定的，那么你应该需要一款 $\text{SSG}$（Static site generator，静态站点生成器）！

SSG 是一种将 Markdown 文档转化为静态网页的工具，它可以帮助你快速建立个人站点，而且一经配置，几乎无需编写 HTML，只需专注于书写 Markdown 文档即可。这之外，$\text{SSG}$ 还可以帮助你自动渲染数学公式、代码块、表格等内容，让你的网页看起来更加美观。

选择一款适合你的 SSG

目前，市面上有很多优秀的 SSG，他们一般都能实现类似的功能，主要是使用的语言各不相同。下面是一些常见的 SSG：

• Vitepress 和 Vuepress：基于 Vue.js 的 SSG。（本网站使用 VitePress 构建）
• Docusaurus：基于 React 的 SSG。
• Hexo：基于 Node.js 的 SSG。
• Pelican：基于 Python 的 SSG。

尽管这些 SSG 基本都是开箱即用的，但可以选择一款用你熟悉的语言编写的 SSG，这样就可以更好地对站点进行自定义。

当然，仅仅是生成静态网页还不够，你还需要一个地方来存放你的网页（包括源文件和生成的 HTML 等文件）。这时，你可以选择将你的网页托管在 GitHub Pages 上。这是一个由 GitHub 提供的静态站点托管服务，你既可以免费地将你的仓库托管在 GitHub 上，还可以免费地使用 GitHub Pages 部署相应的网站（甚至还可以绑定自己的域名）。一举两得！

上述推荐的 SSG 和 GitHub Pages 都有详细的文档，你可以根据自己的需求选择合适的工具，然后按照文档进行配置。

使用 VitePress 建立你的站点

下面，我们将以 VitePress 为例，介绍如何建立你自己的站点。VitePress 是一个基于 Vue.js 和 Vite 的 SSG，适合熟悉这两个语言的用户。

建站的大体思路是，先利用脚手架工具在本地创建一个 VitePress 项目，然后将你的项目仓库托管在 GitHub 上，最后使用 GitHub Pages 部署你的网站。

本地配置

首先，你需要在本地安装 Node.js (版本 18) 和 npm（Node.js 的包管理工具）。如果你不知道如何安装，ChatGPT。然后，可以使用 npm 全局安装 VitePress：

npm add -D vitepress

安装完成后，你可以使用 VitePress 设置向导创建一个 VitePress 项目：

npx vitepress init

向导

向导将会引导你回答几个问题：

┌  Welcome to VitePress!
│
◇  Where should VitePress initialize the config?
│  ./docs（默认）
│
◇  Site title:
│  My Awesome Project（网站标题）
│
◇  Site description:
│  A VitePress Site（网站描述）
│
◆  Theme:
│  ● Default Theme (Out of the box, good-looking docs)（默认即可）
│  ○ Default Theme + Customization（自定义）
│  ○ Custom Theme
└

这样，当向导完成时，一个 VitePress 项目就会被创建当前目录。你可以使用以下命令启动项目：

npm run docs:dev

至此，你的 VitePress 项目已经在本地运行。命令行会给出一个本地访问地址来查看你的网站，通常是 http://localhost:5173。对网站的进一步定制，可以参考 VitePress 的官方文档，里面有详细的配置说明。

部署到 GitHub Pages

而后，应该将你的项目仓库托管在 GitHub 上，这样你就可以使用 GitHub Pages 部署你的网站。首先，在 GitHub 上创建一个新的仓库，假设其地址为 https://github.com/test/test.git ，然后将你的 VitePress 项目推送到这个仓库。注意，这一仓库可以是公开的，也可以是私有的。

git remote add origin https://github.com/test/test.git
git branch -M main
git push -u origin main

这之后，在项目的 .github/workflows 目录中创建一个名为 deploy.yml 的文件，内容如下（内容来自官网）

deploy.yml

# 构建 VitePress 站点并将其部署到 GitHub Pages 的示例工作流程
#
name: Deploy VitePress site to Pages

on:
  # 在针对 `main` 分支的推送上运行。如果你
  # 使用 `master` 分支作为默认分支，请将其更改为 `master`
  push:
    branches: [main]

  # 允许你从 Actions 选项卡手动运行此工作流程
  workflow_dispatch:

# 设置 GITHUB_TOKEN 的权限，以允许部署到 GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# 只允许同时进行一次部署，跳过正在运行和最新队列之间的运行队列
# 但是，不要取消正在进行的运行，因为我们希望允许这些生产部署完成
concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  # 构建工作
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # 如果未启用 lastUpdated，则不需要
      # - uses: pnpm/action-setup@v3 # 如果使用 pnpm，请取消此区域注释
      #   with:
      #     version: 9
      # - uses: oven-sh/setup-bun@v1 # 如果使用 Bun，请取消注释
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm # 或 pnpm / yarn
      - name: Setup Pages
        uses: actions/configure-pages@v4
      - name: Install dependencies
        run: npm ci # 或 pnpm install / yarn install / bun install
      - name: Build with VitePress
        run: npm run docs:build # 或 pnpm docs:build / yarn docs:build / bun run docs:build
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: docs/.vitepress/dist

  # 部署工作
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    needs: build
    runs-on: ubuntu-latest
    name: Deploy
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

而后，你可以在 GitHub 仓库的 Settings 选项卡中找到 Pages。在 Build and deployment > Source 中选择 GitHub Actions。然后等待 GitHub Action 工作流完成，可以期待站点部署到 https://<username>.github.io/[repository]/。

选择 GitHub Actions

购买域名并绑定 GitHub Pages

如果你希望使用自己的域名访问你的网站，可以购买一个域名，然后将其绑定到 GitHub Pages。首先应该进入域名注册商购买一个域名，然后在域名注册商的控制台中找到域名解析设置，添加 A 记录或 AAAA 记录以及 CNAME 记录，将其指向 GitHub Pages 的 IP 地址。

A record:
185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

AAAA record:
2606:50c0:8000::153
2606:50c0:8001::153
2606:50c0:8002::153
2606:50c0:8003::153

CNAME record:
<username>.github.io

修改指向的演示

检测域名解析是否生效

可以在 Linux 或 macOS 的终端中使用 dig 命令检测域名解析是否生效：

dig WWW.EXAMPLE.COM +nostats +nocomments +nocmd

其中，WWW.EXAMPLE.COM 是你的域名。

然后，在GitHub 仓库的 Settings 选项卡中找到 Pages。在 Custom domain 中输入你的域名，点击 Save 保存即可。待域名解析生效后，你就可以通过你的域名访问你的网站了。