Vitepress 建站资源汇总

整理下使用 Vitepress 搭建博客过程中使用过的一些资源和方案

主要参考站点

Vitepress 官方文档

VitePress快速上手中文教程，这个站点扩展很全，包括静态部署选择，样式美化，第三方插件等，都是手把手教程，很细

XaviDocs个人技术文档，借鉴了部分 VitePress 的使用经验

vitepress主题 vitepress-theme-async 源码，借鉴了部分对 Vitepress 的配置和操作逻辑，阅读这些代码对你理解 Vitepress 会有很大帮助

晚阳Crown，借鉴了使用 Cloudflare R2 搭建图床以及使用 Cloudflare 管理域名的经验

详细配置参考

下面会列出 Vitepress 使用细节的一些配置参考文章，包括域名、图床、搜索、评论系统、统计文章等模块

暗黑模式切换动画

参考这篇文章

VitePress 切换暗黑模式丝滑动画

使用 DocSearch 搜索

官方教程 Vitepress - Algolia Search

详细教程 VitePress快速上手中文教程 - DocSearch

参考我的配置

ts 复制代码

import type { DefaultTheme } from 'vitepress'

export const algolia: DefaultTheme.AlgoliaSearchOptions = {
  appId: "appid",
  apiKey: "apikey",
  indexName: 'weizwz',
  placeholder: '搜索文档',
  translations: {
    button: {
      buttonText: '搜索文档',
      buttonAriaLabel: '搜索文档'
    },
    modal: {
      searchBox: {
        resetButtonTitle: '清除查询条件',
        resetButtonAriaLabel: '清除查询条件',
        cancelButtonText: '取消',
        cancelButtonAriaLabel: '取消'
      },
      startScreen: {
        recentSearchesTitle: '搜索历史',
        noRecentSearchesText: '没有搜索历史',
        saveRecentSearchButtonTitle: '保存至搜索历史',
        removeRecentSearchButtonTitle: '从搜索历史中移除',
        favoriteSearchesTitle: '收藏',
        removeFavoriteSearchButtonTitle: '从收藏中移除'
      },
      errorScreen: {
        titleText: '无法获取结果',
        helpText: '你可能需要检查你的网络连接'
      },
      footer: {
        selectText: '选择',
        navigateText: '切换',
        closeText: '关闭',
        searchByText: '搜索提供者'
      },
      noResultsScreen: {
        noResultsText: '无法找到相关结果',
        suggestedQueryText: '你可以尝试查询',
        reportMissingResultsText: '你认为该查询应该有结果？',
        reportMissingResultsLinkText: '点击反馈'
      }
    }
  }
}

添加图片查看器 Fancybox

Fancybox 是一款非常流行且功能强大的 JavaScript 图片查看库，集成可参考这篇文章

VitePress 添加图片查看器 Fancybox

添加不蒜子统计

参考这篇文章

VitePress 添加不蒜子统计

文章统计，自定义首页，归档页，标签页

参考这篇文章

VitePress 统计文章，新建归档页和标签页

其他相关参考资料：

vitepress-theme-async 主题文章统计

Vitepress 新建页面和注册组件

静态部署

部署到 GitHub Pages ，参考文章

VitePress快速上手中文教程 - 部署

主要是建立 GitHub 部署工作流，项目根目录建立文件 .github/workflows/main.yml，我之前的配置如下：

yml 复制代码

# 将静态内容部署到 GitHub Pages 的简易工作流程
name: Deploy static content to Pages

# env:
#   VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
#   VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}

on:
  # 仅在推送到默认分支时运行。
  push:
    branches: ['main']，暂停部署到 GitHub pages

  # 这个选项可以使你手动在 Action tab 页面触发工作流
  workflow_dispatch:

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

# 允许一个并发的部署
concurrency:
  group: 'pages'
  cancel-in-progress: true

jobs:
  # 构建
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          persist-credentials: false
          fetch-depth: 0
  # github page deploy
      - name: Set up pnpm
        uses: pnpm/action-setup@v4
        with:
          version: 9
      - name: Set up Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'
      - name: Setup Pages
        uses: actions/configure-pages@v4
      - name: Install dependencies
        run: pnpm install
      - name: Build
        run: pnpm run build
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          # Upload dist repository
          path: './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
    
      # vercel deploy
      # - name: Restore file modification time 🕒
        # run: find docs/post -name '*.md' | while read file; do touch -d "$(git log -1 --format="@%ct" "$file")" "$file"; done
        # run: "git ls-files -z | while read -d '' path; do touch -d \"$(git log -1 --format=\"@%ct\" \"$path\")\" \"$path\"; done"
      # - name: Install Vercel-cli🔧
      #   run: npm install --global vercel@latest
      # - name: Pull Vercel Environment Information
      #   run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}
      # - name: Build Project Artifacts
      #   run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}
      # - name: Deploy Project Artifacts to Vercel
      #   run: vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}