告别传统博客模式，VitePress 让笔记自动生成博客

  大家好，我是木川

自媒体平台那么多，为什么还要搭建自己的博客？

1）在自媒体平台上，你受限于平台的规则和算法，而在博客上，你可以自由地表达自己的想法，不受任何限制

2）搜索引擎优化：博客通常更容易被搜索引擎收录，通过优化关键词和内容，可以吸引更多的流量

3）建立个人品牌：博客是建立和展示个人专业形象和品牌的理想场所。通过持续发布高质量的内容，你可以成为某个领域的意见领袖，吸引一群忠实的读者

为什么选择 VitePress ？

1）不用一直折腾，专心写作。从最早用的 WordPress、Hexo、掘金等，每次都会有新的平台出来，耗费太多精力

2）内容基于 Markdown 编写。自己用 Markdown 写的笔记，就可以生成博客

3）生成的静态文件可以托管在 Github 上，无须购买域名，即可使用 Github 分配的网址进行访问

VitePress 是一款静态站点生成器  (SSG) ，专为构建快速、以内容为中心的网站而设计。简而言之，VitePress 获取用 Markdown 编写的源内容，为其应用主题，并生成可以轻松部署在任何地方的静态 HTML 页面。

本文将介绍通过 VitePress 基于 Markdown 笔记文档生成博客，并部署到 Github 上，以及笔记发生变化时，自动更新博客

最终的效果如下：https://muchuang1024.github.io/

一、创建笔记仓库

为了笔记文档和博客网站分开管理，所以需要单独在创建一个笔记仓库 docs

建议托管在 Github 上面，方便后面的自动更新

1、拉取到本地

在 Github 创建好仓库后，拉取到本地

git clone git@github.com:username/docs.git # 拉取到本地
cd docs # 进入目录

2、添加笔记文档

可以使用 Obsidian 软件管理 Markdown 笔记文档，然后使用 Git 提交

git add . # 添加笔记文档
git commit -m 'ADD 提交' # 提交到本地仓库
git push origin main # 提交到远程仓库

二、创建博客仓库

在 Github 创建好博客仓库 username.github.io，拉取到本地

1、拉取到本地

git clone git@github.com:username/username.github.io.git
cd username.github.io # 进入目录

2、安装 VitePress 依赖

yarn add -D vitepress

3、构建项目

VitePress 附带一个脚手架，可帮助您构建基本项目

npx vitepress init

输入相应设置，自动生成相关代码

4、添加笔记文档

在博客仓库添加子项目：笔记文档仓库 docs

# 添加笔记文档仓库作为子项目
git submodule add -f git@github.com:username/docs.git docs
# 拉取到本地
git submodule update --init --recursive

5、项目目录结构

各个文件含义

.vitepress：VitePress 配置
docs:  笔记仓库
index.md: 首页
node_modules: 安装的依赖
package.json：依赖管理
package-lock.json：安装依赖的版本

配置文件 ( .vitepress/config.mts) 允许自定义 VitePress 站点的各个配置

import { defineConfig } from 'vitepress'

// https://vitepress.dev/reference/site-config
export default defineConfig({
  title: '木川博客',

  description: '个人笔记',

  srcDir: '.', // 存放文档的路径（index.md 的父目录），VitePress 会基于这个目录来编译和生成静态网站；如果配置为 ., 则是对应的项目根目录，scDir 下 必须要有一个 index.md，配置主页布局

  themeConfig: {
    // https://vitepress.dev/reference/default-theme-config
    nav: [ // 首页右上角导航栏
      {
        text: 'Home',
        link: '/' // 链接路径，这个路径应该是相对于 `srcDir` 的。比如 `/docs/test` 指向的是 `scDir/docs/test.md`
      },
      {
        text: 'Examples',
        link: '/docs/markdown-examples' // 指向笔记库的文档路径
      }
    ],

    sidebar: [ // 详情页侧边栏
      {
        text: 'Examples',
        items: [
          {
            text: 'Markdown Examples',
            link: '/docs/markdown-examples' // 指向笔记库的文档路径
          },

          {
            text: 'Runtime API Examples',
            link: '/docs/api-examples'
          }
        ]
      }
    ],

    socialLinks: [
      {
        icon: 'github',
        link: 'https://github.com/vuejs/vitepress'
      }
    ]
  }
})

6、自动生成侧边栏

侧边栏默认通过 sidebar 字段配置

sidebar: [
  {
    text: 'Examples',
    items: [
      { text: 'Markdown Examples', link: '/markdown-examples' },
      { text: 'Runtime API Examples', link: '/api-examples' }
    ]
  }
]

如果文章很多，都需要手动配置，很耗费时间，并且修改后还需要手动同步。所以推荐安装插件，自动配置侧边栏

安装侧边栏插件

npm install vite-plugin-vitepress-auto-sidebar

在 .vitepress/config.mts 文件中使用插件，将会根据文章目录生成侧边栏

import AutoSidebar from 'vite-plugin-vitepress-auto-sidebar'

export default defineConfig({
  vite: {
    plugins: [
      AutoSidebar({
        path: '.',
        collapsed: false,
        ignoreList: ['.obsidian', '.git', 'node_modules']
      })
    ]
  }
})

7、本地运行

通过 执行 dev 命令，可以在本地预览

yarn docs:dev

通过执行 build 命令，生成构建好的静态 dist 文件，存放在 .vitepress/dist 下面

yarn docs:build

8、部署到 Github

gh-pages 是一个用于 GitHub 项目的分支，通常用于托管静态网站内容。当你在该分支上推送静态网页文件时，GitHub 会自动为你分配一个网址，用于展示你的网站。

本文采用 Github gh-pages 部署个人博客网站

1）安装 gh-pages 依赖

在您的项目中，安装 gh-pages 包，它可以帮助您将构建的静态 dist 文件推送到 gh-pages 分支

在 package.json 中添加一个脚本，当执行 yarn depoly 命令时，将上面构建的 dist 文件推送到 gh-pages 分支

"scripts": {
  "deploy": "gh-pages -d dist"
}

2）部署到 Github gh-pages 分支

运行部署脚本，这将自动将 dist 目录（或您在 VitePress 配置中指定的其他输出目录）中的文件推送到 gh-pages 分支

yarn deploy

3）配置 GitHub Pages

在 GitHub 仓库的设置（Settings）中，找到 “GitHub Pages” 部分。在“Source”下拉菜单中选择 gh-pages 分支

9、访问网站

静态文件推送到 gh-pages 分支后，您的 VitePress 网站应该可以通过 username.github.io 访问了，其中 username 是您的 GitHub 用户名

如果博客仓库名字为 username.github.io，则可以通过 https://username.github.io 访问 如果博客仓库名字为 repository，则可以通过 https://username.github.io/repository 访问

三、自动更新

看到这里，你应该知道了，如果笔记文档发送变化，需要在博客仓库下手动更新的，下面分享一种通过 Github Actions 的方法实现子仓库笔记更新时，自动更新博客网站

1、子项目添加 Actions

前往子项目 Github 仓库地址，添加 Actions，实现子项目 markdown 文档更新时，同步推送更新到父项目

name: Send submodule updates to parent repo

on:
  workflow_dispatch:
  push:
    branches: 
      - main

jobs:
  update:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3
        with: 
          repository: muchuang1024/muchuang1024.github.io
          token: ${{ secrets.PRIVATE_TOKEN_GITHUB }}
          submodules: true

      - name: Pull & update submodules recursively
        run: |
          git submodule update --init --recursive
          git submodule update --recursive --remote

      - name: Commit
        run: |
          git config user.email "actions@github.com"
          git config user.name "GitHub Actions - update submodules"
          git add --all
          git commit -m "Update submodules" || echo "No changes to commit"
          git push

上面的配置中，需要用到 PRIVATE_TOKEN_GITHUB，这样 Actions 才能推送代码到 Github 仓库

那如何设置 PRIVATE_TOKEN_GITHUB 呢？

1）前往个人中心 https://github.com/settings/tokens 创建 accees_token

2）前往子项目 https://github.com/muchuang1024/docs/settings/secrets/actions/new 添加PRIVATE_TOKEN_GITHUB，对应的值为上一步创建的 accees_token

运行上面的 Actions，没有报错则代表正常

2、父项目添加 Actions

前往父项目 Github 仓库地址，添加 Actions，父项目代码更新后，立即更新 Vitepress 站点

name: Deploy to GitHub Pages

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
   - uses: pnpm/action-setup@v2
        with:
          version: 7.26.3
      - uses: actions/setup-node@v3
        with:
          node-version: 16
          cache: pnpm
      - name: Install dependencies
        run: pnpm install

      - name: Build the documentation
        run: pnpm run docs:build

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.PRIVATE_TOKEN_GITHUB }}
          publish_dir: .vitepress/dist
          ref: gh-pages

前往父项目添加 PRIVATE_TOKEN_GITHUB secret

运行上面的 Actions，没有报错则代表正常

四、总结

本文主要介绍如何使用 VitePress 搭建个人博客，并部署到 Github 上，以及如何实现笔记文档更新时自动更新博客网站。

文章分为以下三个部分：

1、为什么搭建个人博客：分析了在自媒体平台上创作的局限性，强调了博客在搜索引擎优化、个人品牌建立方面的优势。

2、为什么选择VitePress：指出 VitePress 作为静态站点生成器的优势，包括简化写作流程、基于Markdown 编写内容、易于部署到 Github 等。

3、 搭建和部署过程：详细介绍了创建笔记仓库、创建博客仓库、安装 VitePress 依赖、构建项目、添加笔记文档、配置 VitePress、自动生成侧边栏、本地运行、部署到 Github、配置 GitHub Pages、访问网站等步骤。

文章还提供了自动更新博客网站的解决方案，通过 Github Actions实现子仓库笔记更新时，自动同步推送更新到父项目，并部署到 VitePress 站点

---

今天的分享就到这里了，欢迎加我微信围观高质量朋友圈，还有机会和 500 位 AI 编程高手一起交流

关注我的星球，分享 AI 技术和读书心得，置顶贴领取价值 399 元 的 AI 大礼包。