基于 VitePress + Element Plus 的卡片风博客主题。
以此致敬我的博客启蒙样式hexo-theme-butterfly
目标很简单：一键部署上线，轻松更新内容。
workflow一键部署上线，写 Markdown/VUE页面、推送、自动上线。
我的博客:https://57darling02.github.io
博客模板展示:https://vitepress.57d02.cn
正式使用提醒：本项目采用双仓库模式：
主题仓库：只负责主题、构建、部署
知识库仓库：负责文章、图片、站点配置
Setup Blog 会自动创建私密知识库，并把知识库同步到主题仓库的 posts/ 工作区。线上 CI 必须配置 WIKI_URL，本地 posts/ 只用于主题开发。
配置只认知识库里的 site_config.yml。主题仓库里的site_config.example.yml 只是参考模板。
这是推荐用法，不需要在电脑上安装 Node.js、pnpm 或任何本地环境。
点击 GitHub 页面右上角 Fork，把本仓库复制到你自己的账号下。
推荐建议仓库名设为：
你的用户名.github.io
以此作为站点域名。
创建一个 GitHub PAT，用来让初始化工作流帮你创建知识库、配置 secrets、触发部署。
GitHub 头像 -> Settings -> Developer settings -> Personal access tokens -> Tokens (classic)
推荐勾选：
repo
workflow
复制生成的 token。它只显示一次。
回到你的主题仓库，添加 secret：
Settings -> Secrets and variables -> Actions -> New repository secret
名称填：
SETUP_PAT
值粘贴刚刚生成的 token。
如果 GitHub 提示 Fork 后的 workflow 被禁用，点击允许启用。
Actions -> Setup Blog -> Run workflow
填写：
wiki_repo_name：你的知识库仓库名，例如my-blog-wikiwiki_branch：默认main
运行后，它会自动：
- 使用 57Darling02/wiki_template 创建你的知识库仓库
- 知识库仓库固定创建为私密仓库
- 给主题仓库配置
WIKI_URL、WIKI_BRANCH、PAT - 给知识库仓库配置
BLOG_REPO和PAT - 尝试把 GitHub Pages 设置为
GitHub Actions - 创建知识库后，由知识库工作流通知主题仓库触发第一次部署
初始化成功后，
SETUP_PAT只在你重新运行Setup Blog时才需要；如果暂时不用，可以从主题仓库 secrets 里删除。
如果 Pages 自动配置失败，手动进入：
Settings -> Pages
把 Source 设置为：
GitHub Actions
所有可定制的内容(站点配置、首页效果、文章、自定义页面等等)都只需要在知识库中改动！ 详情见README：https://github.com/57Darling02/wiki_template/ 或https://vitepress.57d02.cn/p/d2e9fe6f
简单介绍： 只需要在知识库里维护一下内容
site_config.yml
public/
文章目录/
其中public用于非文章专属的资源。
---
title: Hello World
date: 2026-01-01
author: Me
layout: doc
---
# Hello World文章需要带 layout: doc：
layout: doc 会进入首页、归档、标签等文章流。
如果希望展示自己的页面，本文也提供VUE完成自己的页面 例如友链页面的效果 在知识库中的配置见模板仓库的FriendLink文件夹
比如我希望xxx/FriendLink创建页面，则只需要在目标链接对应目录下完成页面：
- 写好vue页面于FriendLink/FriendLinkPage.vue
- 在FriendLink/index.md中引入，配置
layout: page
---
title: FriendLink
layout: page
---
<script setup>
import FriendLinkPage from './FriendLinkPage.vue'
</script>
<ClientOnly>
<FriendLinkPage />
</ClientOnly>然后在 site_config.yml 的 menuItems 中手动配置,告知访客入口即可。
短内容可以先使用自定义 layout，例如：
---
layout: shuoshuo
date: 2026-01-01
---
今天也在认真生活。这类内容当前只会被构建保留，不会影响现有文章展示；之后可以再做专门的“说说”页面。
推送知识库后，它会通知主题仓库重新部署。
部署完成后，在仓库的 Actions 页面可以看到构建状态；在 Settings -> Pages 可以看到访问地址。
如果你的个性化内容都在知识库中，那么可以用本仓库的 update_theme.sh 粗暴更新主题：
bash update_theme.sh它会从上游主题仓库重置源码仓库。执行前请确认你的自定义内容不在源码文件里。
如果自动初始化失败，可以手动用 57Darling02/wiki_template 创建私密知识库，然后在主题仓库配置 WIKI_URL、WIKI_BRANCH、PAT 三个 Actions secrets。
知识库自动触发主题仓库重建需要在知识库里配置 BLOG_REPO 和 PAT，并添加 repository_dispatch workflow。正常用户优先使用 Setup Blog，不需要手动做这些。
只有当你想本地预览或开发主题时，才需要这一节。
安装依赖：
pnpm install本地预览：
pnpm dev构建：
pnpm docs:build在源码仓库根目录创建 .env.local：
WIKI_URL=https://github.com/yourname/your-private-wiki.git
WIKI_BRANCH=main
PAT=ghp_xxx
.env.local 不会提交。之后直接运行：
pnpm dev脚本会先同步知识库，再启动 VitePress。
pnpm prepare-content
pnpm dev
pnpm docs:build
pnpm previewVitePress-Butterfly/
├── .vitepress/ # Theme core
├── scripts/
│ └── prepare-content.js # Content preparation
├── posts/ # Content workspace
├── public/ # Theme public assets
├── site_config.example.yml # Config template
├── package.json
└── update_theme.sh
MIT © 2024-present 57Darling02
