当前位置:   article > 正文

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

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/

7c64fb0f955bc7d7a0238da939e5b1c1.png 192ee0a8f1c1e4be6137c4ac5faa60f5.png

一、创建笔记仓库

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

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

1、拉取到本地

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

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

2、添加笔记文档

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

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

二、创建博客仓库

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

1、拉取到本地

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

2、安装 VitePress 依赖

yarn add -D vitepress

3、构建项目

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

npx vitepress init

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

2100829f10e7b41a6dca32238094d75f.png

4、添加笔记文档

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

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

5、项目目录结构

c55155c55e266f28de8d68138e397593.png

各个文件含义

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

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

  1. import { defineConfig } from 'vitepress'
  2. // https://vitepress.dev/reference/site-config
  3. export default defineConfig({
  4.   title: '木川博客',
  5.   description: '个人笔记',
  6.   srcDir: '.'// 存放文档的路径(index.md 的父目录),VitePress 会基于这个目录来编译和生成静态网站;如果配置为 ., 则是对应的项目根目录,scDir 下 必须要有一个 index.md,配置主页布局
  7.   themeConfig: {
  8.     // https://vitepress.dev/reference/default-theme-config
  9.     nav: [ // 首页右上角导航栏
  10.       {
  11.         text: 'Home',
  12.         link: '/' // 链接路径,这个路径应该是相对于 `srcDir` 的。比如 `/docs/test` 指向的是 `scDir/docs/test.md`
  13.       },
  14.       {
  15.         text: 'Examples',
  16.         link: '/docs/markdown-examples' // 指向笔记库的文档路径
  17.       }
  18.     ],
  19.     sidebar: [ // 详情页侧边栏
  20.       {
  21.         text: 'Examples',
  22.         items: [
  23.           {
  24.             text: 'Markdown Examples',
  25.             link: '/docs/markdown-examples' // 指向笔记库的文档路径
  26.           },
  27.           {
  28.             text: 'Runtime API Examples',
  29.             link: '/docs/api-examples'
  30.           }
  31.         ]
  32.       }
  33.     ],
  34.     socialLinks: [
  35.       {
  36.         icon: 'github',
  37.         link: 'https://github.com/vuejs/vitepress'
  38.       }
  39.     ]
  40.   }
  41. })

6、自动生成侧边栏

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

  1. sidebar: [
  2.   {
  3.     text: 'Examples',
  4.     items: [
  5.       { text: 'Markdown Examples', link: '/markdown-examples' },
  6.       { text: 'Runtime API Examples', link: '/api-examples' }
  7.     ]
  8.   }
  9. ]

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

安装侧边栏插件

npm install vite-plugin-vitepress-auto-sidebar

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

import AutoSidebar from 'vite-plugin-vitepress-auto-sidebar'
  1. export default defineConfig({
  2.   vite: {
  3.     plugins: [
  4.       AutoSidebar({
  5.         path: '.',
  6.         collapsed: false,
  7.         ignoreList: ['.obsidian''.git''node_modules']
  8.       })
  9.     ]
  10.   }
  11. })

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 分支

  1. "scripts": {
  2.   "deploy""gh-pages -d dist"
  3. }

2)部署到 Github gh-pages 分支

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

yarn deploy

3)配置 GitHub Pages

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

3737ba52c151dba8fe1b6aa8f150a41d.png

9、访问网站

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

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

f01f5c0705990d5283087924980d47b3.png

三、自动更新

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

1、子项目添加 Actions

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

  1. name: Send submodule updates to parent repo
  2. on:
  3.   workflow_dispatch:
  4.   push:
  5.     branches: 
  6.       - main
  7. jobs:
  8.   update:
  9.     runs-on: ubuntu-latest
  10.     steps:
  11.       - uses: actions/checkout@v3
  12.         with: 
  13.           repository: muchuang1024/muchuang1024.github.io
  14.           token: ${{ secrets.PRIVATE_TOKEN_GITHUB }}
  15.           submodules: true
  16.       - name: Pull & update submodules recursively
  17.         run: |
  18.           git submodule update --init --recursive
  19.           git submodule update --recursive --remote
  20.       - name: Commit
  21.         run: |
  22.           git config user.email "actions@github.com"
  23.           git config user.name "GitHub Actions - update submodules"
  24.           git add --all
  25.           git commit -m "Update submodules" || echo "No changes to commit"
  26.           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

9a5b1d8b031e3c261c914094145d7e40.png

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

2、父项目添加 Actions

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

  1. name: Deploy to GitHub Pages
  2. on:
  3.   push:
  4.     branches:
  5.       - main
  6. jobs:
  7.   deploy:
  8.     runs-on: ubuntu-latest
  9.     steps:
  10.       - uses: actions/checkout@v3
  11.         with:
  12.           fetch-depth: 0
  13.    - uses: pnpm/action-setup@v2
  14.         with:
  15.           version: 7.26.3
  16.       - uses: actions/setup-node@v3
  17.         with:
  18.           node-version: 16
  19.           cache: pnpm
  20.       - name: Install dependencies
  21.         run: pnpm install
  22.       - name: Build the documentation
  23.         run: pnpm run docs:build
  24.       - name: Deploy to GitHub Pages
  25.         uses: peaceiris/actions-gh-pages@v3
  26.         with:
  27.           github_token: ${{ secrets.PRIVATE_TOKEN_GITHUB }}
  28.           publish_dir: .vitepress/dist
  29.           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 编程高手一起交流

ca4f22dc07cd678c1a297aacd7193f10.png

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

95ee9b6723cb323570da46791c4f3c61.jpeg

本文内容由网友自发贡献,转载请注明出处:【wpsshop博客】
推荐阅读
相关标签
  

闽ICP备14008679号