back
loading skill details...
从零搭建 Quartz v4 + GitHub Pages 博客，将 Obsidian 知识库发布为静态网站。 当用户提到"搭建 Quartz 博客"、"Obsidian 发布博客"、"部署 Obsidian 到 GitHub Pages"、 "quartz setup"、"obsidian quartz blo...
---
name: obsidian-quartz-blog-setup
description: >
从零搭建 Quartz v4 + GitHub Pages 博客，将 Obsidian 知识库发布为静态网站。
当用户提到"搭建 Quartz 博客"、"Obsidian 发布博客"、"部署 Obsidian 到 GitHub Pages"、
"quartz setup"、"obsidian quartz blog"、"发布知识库到网站"、"搭建个人博客"、
"把我的笔记部署到网上"、"obsidian to website"时触发此 skill。
这是一个首次搭建的工作流——如果用户已经搭建好 Quartz 只是要推送更新，
应该触发 obsidian-wiki-blog-push 而非本 skill。
---
# Obsidian Quartz Blog Setup
从零搭建 Quartz v4 + GitHub Pages，将 Obsidian 知识库发布为静态博客。
## 工作流总览
```
询问配置信息 → 环境检查 → 安装 Quartz → 初始化 → 同步笔记
→ 本地预览 → 配置 quartz.config.ts → GitHub 仓库指引
→ 绑定远程仓库 → 创建 deploy.yml → 推送到 GitHub
```
## Step 0: 收集配置信息
在开始任何操作之前，一次性询问用户以下所有信息：
1. **Obsidian 知识库路径** — vault 的绝对路径（如 `C:\Users\xxx\my-vault`）
2. **Quartz 项目目录** — 希望在哪里创建 Quartz 博客项目（如 `~/projects/my-blog`）
3. **GitHub 仓库地址** — 完整的远程仓库 URL（如 `https://github.com/username/repo.git`）。如果还没创建，提醒用户先去 GitHub 创建一个**空仓库**（不要添加 README、.gitignore 或 license）
4. **站点标题 (pageTitle)** — 博客的标题，显示在浏览器标签页和网站头部
5. **baseUrl** — GitHub Pages 的访问地址，不带 `https://`：
- 用户站点：`username.github.io`
- 项目站点：`username.github.io/repo`
将所有问题放在一条消息中，格式清晰，方便用户一次性回复。
## Step 1: 环境检查
检查以下工具是否可用：
```bash
git --version
node --version
npm --version
```
Quartz v4 需要 Node.js 20 或以上版本。如果版本过低，提示用户升级。
同时确认 Obsidian vault 目录存在：
```bash
ls "<vault-path>"
```
如果有工具缺失，指引用户安装：
- Git: https://git-scm.com/downloads
- Node.js (推荐 LTS): https://nodejs.org/
## Step 2: 安装 Quartz
先检查 Quartz 项目目录是否已存在 `quartz.config.ts`：
```bash
ls "<project-dir>/quartz.config.ts" 2>/dev/null && echo "EXISTS" || echo "NOT_EXISTS"
```
**如果 NOT_EXISTS**（首次安装）：
```bash
git clone https://github.com/jackyzha0/quartz.git "<project-dir>"
cd "<project-dir>"
npm install
```
如果 `npm install` 失败，常见原因：
- Node.js 版本太低（需要 20+）→ 升级 Node.js
- npm 缓存问题 → 执行 `npm cache clean --force` 后重试
**如果 EXISTS**（之前安装过）：
跳过 clone 和 npm install，直接进入 Step 3。输出提示：
> 检测到 Quartz 已安装，跳过安装步骤。
## Step 3: 初始化 Quartz
```bash
cd "<project-dir>"
npx quartz create
```
这是一个交互式命令，引导用户选择：
- 内容来源选 **"Obsidian"**
- 组织方式选 **"Copy the markdown files into the content folder"**（因为后续步骤会统一复制笔记）
## Step 4: 同步笔记到 Content 目录
将 Obsidian vault 中的所有 markdown 文件复制到 Quartz 的 content 目录。
**排除项**（不复制）：
- `.obsidian/` — Obsidian 配置目录
- `.trash/` — 回收站
- `.git/` — Git 仓库
- `node_modules/` — Node 依赖
- 隐藏文件（以 `.` 开头的文件）
**Windows (PowerShell) — 使用 robocopy**：
```powershell
robocopy "<vault-path>" "<project-dir>/content" *.md /S /XO /XD .obsidian .trash .git node_modules /XF ".*"
```
robocopy 退出码 0-7 均表示正常（0=无变更, 1=有复制, 2=有额外文件等），8+ 才是错误。
**macOS / Linux — 使用 rsync**：
```bash
rsync -av --update \
--exclude='.obsidian/' --exclude='.trash/' --exclude='.git/' \
--exclude='node_modules/' --exclude='.*' \
--include='*.md' --include='*/' --exclude='*' \
"<vault-path>/" "<project-dir>/content/"
```
如果 vault 中有附件目录（如 `attachments/`、`assets/`、`images/`），也一并复制。
## Step 5: 本地构建预览
启动本地开发服务器，让用户预览网站效果：
```bash
cd "<project-dir>"
npx quartz build --serve
```
服务器默认运行在 http://localhost:8080。提示用户：
> 本地预览服务器已启动，可以在浏览器中打开 http://localhost:8080 查看效果。
> 确认无误后，按 Ctrl+C 停止服务器，我们继续后续配置。
## Step 6: 配置 quartz.config.ts
打开 `<project-dir>/quartz.config.ts`，修改以下配置项：
```typescript
const config: QuartzConfig = {
configuration: {
pageTitle: "<用户提供的站点标题>",
baseUrl: "<用户提供的 baseUrl>",
// ... 其余配置保持默认
},
}
```
向用户解释：
- `pageTitle` — 显示在浏览器标签页和网站头部标题
- `baseUrl` — 用于生成正确的页面链接和资源路径，**不要**带 `https://`，**不要**末尾加 `/`
## Step 7: GitHub 仓库设置指引
这是**提示用户手动操作**的步骤，不在本地执行。向用户展示以下指引：
> **请在 GitHub 上完成以下操作：**
>
> 1. 访问 https://github.com/new 创建一个新的空仓库
> - **重要**：仓库必须是**完全空的**——不要勾选 "Add a README file"、".gitignore" 或 "license"
> 2. 创建完成后，进入仓库的 **Settings → Pages**
> 3. 在 "Build and deployment" 部分，将 **Source** 设置为 **GitHub Actions**
>
> 完成后请告诉我，我将继续配置自动部署。
等待用户确认后继续。
## Step 8: 绑定远程仓库
将 Quartz 项目的 origin 从官方仓库改为用户的 GitHub 仓库：
```bash
cd "<project-dir>"
git remote set-url origin <用户的-github-仓库地址>
git remote -v
```
验证 `origin` (fetch) 和 `origin` (push) 都指向用户的仓库。
## Step 9: 创建 GitHub Actions 部署工作流
创建 `.github/workflows/deploy.yml`：
```bash
mkdir -p "<project-dir>/.github/workflows"
```
写入以下内容到 `<project-dir>/.github/workflows/deploy.yml`：
```yaml
name: Deploy Quartz site to GitHub Pages
on:
push:
branches:
- v4
workflow_dispatch:
permissions:
contents: read
pages: write
id-token: write
concurrency:
group: "pages"
cancel-in-progress: false
jobs:
build:
runs-on: ubuntu-22.04
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: actions/setup-node@v4
with:
node-version: 22
- name: Install Dependencies
run: npm ci
- name: Build Quartz
run: npx quartz build
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: public
deploy:
needs: build
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
```
**`workflow_dispatch`** 允许手动触发部署，作为 push 触发失败时的后备方案。
### 清理继承的 Quartz 模板 Workflow
Quartz 官方仓库自带多个 workflow（`ci.yaml`、`build-preview.yaml`、`deploy-preview.yaml`、`docker-build-push.yaml`），它们包含 `if: github.repository == 'jackyzha0/quartz'` 条件，在用户的仓库中永远不会执行，只会在 Actions 页面产生多余的 skipped 记录。
创建 deploy.yml 后，删除这些无用 workflow：
```bash
rm "<project-dir>/.github/workflows/ci.yaml"
rm "<project-dir>/.github/workflows/build-preview.yaml"
rm "<project-dir>/.github/workflows/deploy-preview.yaml"
rm "<project-dir>/.github/workflows/docker-build-push.yaml"
```
向用户说明：每次推送到 `v4` 分支时，GitHub Actions 会自动构建并部署网站到 GitHub Pages。
## Step 10: 推送到 GitHub
```bash
cd "<project-dir>"
git add .
git commit -m "init quartz blog"
git branch -M v4
git push -u origin v4
```
推送成功后，向用户报告：
- 提交信息
- 推送到的分支
- 部署状态查看地址：`https://github.com/<username>/<repo>/actions`
- 首次部署通常需要 1-3 分钟
- 部署完成后网站将在 GitHub Pages URL 上线
### 首次推送后 Actions 未触发的处理
GitHub Actions 有一个已知问题：首次推送包含 workflow 文件的提交时，workflow 可能不会被触发。如果推送后在 Actions 页面看不到运行记录：
1. **先等待 1-2 分钟**，GitHub 有时需要时间处理
2. **手动触发**：进入 Actions → 选择 deploy workflow → 点击 "Run workflow" → 选择 v4 分支运行
3. **再推一个小改动**触发 push 事件：
```bash
cd "<project-dir>"
git commit --allow-empty -m "chore: trigger deploy"
git push origin v4
```
## 后续更新
当用户需要更新博客内容时，应触发 `obsidian-wiki-blog-push` skill（而非本 skill）来完成增量同步和推送。本 skill 仅用于首次搭建。
## 安全规则
- **绝不删除**用户 Obsidian vault 中的任何文件
- **覆盖前确认** — 覆盖已有的 Git 仓库或配置文件前，征得用户明确同意
- **修改 Git remote 前确认**
- 执行每一条命令前，向用户简要解释其作用
- 针对用户的操作系统给出对应命令（Windows PowerShell vs macOS/Linux bash）
## 自我进化机制
每次执行完本 Skill 后：
1. 评估输出是否达成目标（pass / fail）
2. fail 时反思失败原因，在 diary/YYYY-MM-DD.md 追加「失败案例 + 修复建议」
3. 某条修复建议在最近 3 次执行中被反复提及时，提炼为正式规则，提交 PR 修改本 SKILL.mddon't have the plugin yet? install it then click "run inline in claude" again.