简单使用vitepress快速搭建一个文档网站

你好，今天简单写写建站。

VitePress 是一个静态站点生成器 (SSG)，类似的项目有docsify、VuePress、hexo。

大概原理就是用 Markdown 编写的内容生成可以轻松部署到任何地方的静态 HTML 页面。

VitePress 附带一个专为技术文档设计的默认主题。你现在正在阅读的这个页面以及 Vite、Rollup、Pinia、VueUse、Vitest、D3、UnoCSS、Iconify 等文档都是基于这个主题的。

VitePress 和 VuePress类似的一个项目。最初的 VuePress 基于 Vue 2 和 webpack。借助 Vue 3 和 Vite，VitePress 提供了更好的开发体验、更好的生产性能、更精美的默认主题和更灵活的自定义 API。

使用下来感觉和VuePress差不多。插件和主题都很少，开箱即用的插件和主题也基本够用了。

前置条件

nodejs 18+
pnpm 包管理

初始化项目

shell 复制代码

## 安装pnpm
npm i pnpm -g
## 初始化项目
## 创建一个空目录
mkdir doc-demo
cd doc-demo
## 初始化node项目
pnpm init
# 安装vitepress
pnpm add -D vitepress
pnpm vitepress init

初始化后的目录结构如下：

shell 复制代码

|-- docs
|   |-- .vitepress
|   |-- api-examples.md
|   |-- index.md
|   `-- markdown-examples.md
|-- node_modules
|   `-- vitepress
|-- package.json
`-- pnpm-lock.yaml

启动项目pnpm run docs:dev，访问http://localhost:5173/就可以看到项目网站已经搭建好了。

多语言支持

由于网站默认是英文的，中文翻译需要配置下。

这里使用插件vitepress-i18n来完成这个功能。

shell 复制代码

## 安装插件
pnpm add -D vitepress-i18n

修改docs/.vitepress/config.js文件。

js 复制代码

/**
 * 多语言配置
 */
const defaultLocale = 'zhHans';
const defineSupportLocales = [
  { label: defaultLocale, translateLocale: defaultLocale }
];

// https://vitepress.dev/reference/site-config
export default defineConfig({
  title: "doc-demo",
  description: "A VitePress Site",
  themeConfig: {}, //此处省略
  locales: generateI18nLocale({
    defineLocales: defineSupportLocales,
    rootLocale: defaultLocale,
  })
})

启动项目pnpm run docs:dev，访问http://localhost:5173/就可以看到网站已经默认是中文的了。

多语言的支持具体可以参考插件的文档。此处只是修改了默认语言。

发布

原理就是使用pnpm run docs:build命令生成静态文件，将生成的静态文件上传到服务器即可。

但是这里借助github的pages来完成这个功能，所以需要编写一个脚本文件。

具体的内容可以参考vitepress官方文档。

在项目的 .github/workflows 目录中创建一个名为 deploy.yml 的文件，其中包含这样的内容：

yaml 复制代码

# 构建 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，请取消注释
      # - 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

如果访问有问题就要确保 VitePress 中的 base 选项配置正确。

绑定域名

github的pages默认提供了一个访问url。但是如果想绑定自己的域名，需要在github的settings中配置。

具体的配置可以参考github的文档。这里只是简单描述下大概流程。

绑定域名。在github的用户settings中配置，并点击其中的 Pages选项第四步，在右侧输入要验证的域名，并点击 Add domain按钮。
绑定仓库域名。进入仓库界面，并点击上方的 Settings按钮。在左侧栏的 Code and automation 部分，点击 Pages 选项，在右侧的栏目中，将域名填写进去并点击Save按钮。Github Page 将花费一点时间完成对 DNS 配置的检查。

整个过程还是挺快的。具体还涉及到DNS的相关配置。这里就不细说了。

后续计划

增加https的支持。
开发插件支持mermaid展示。
开发插件支持更多的文档属性，兼容hexo。

关于作者

来自全栈程序员nine的探索与实践，持续迭代中。