这是一份早期发布方案记录：当时的目标是用 Obsidian 写作、Quartz 渲染，并托管到 GitHub Pages。现在主站已经迁移到 AstroWind，这篇更多作为方案留档。

目标：用 Obsidian 写笔记 → 通过 Quartz 转成美观的数字花园网站 → 免费托管在 GitHub Pages 上，每次 push 自动更新。

前置条件（请先全部准备好）

• 已安装 Node.js 20+（推荐 22.x） → https://nodejs.org/
• 已安装 Git → https://git-scm.com/downloads
• 有 GitHub 账号
• 已安装 Obsidian 并有一个你想公开的知识库（vault）

完整步骤（从0开始）

步骤 1：创建 GitHub 仓库

1. 登录 https://github.com
2. 点击右上角 “+” → New repository
3. Repository name：建议两种命名方式，任选其一：
   • 你的用户名.github.io → 网站最终地址为 https://你的用户名.github.io
   • 笔记名 或 garden 等 → 网站地址为 https://你的用户名.github.io/笔记名
4. 不要勾选 “Add a README file”、“Add .gitignore” 或 license
5. 点击 Create repository
6. 复制仓库地址（HTTPS 格式），形如：

   https://github.com/你的用户名/你的仓库名.git

步骤 2：本地安装并初始化 Quartz

1. 打开终端（Windows 用 PowerShell 或 Git Bash，Mac 用 Terminal）

2. 找一个你想存放 Quartz 的文件夹，例如：

   cd ~/Documents

3. 克隆 Quartz v4（官方推荐方式）：

   git clone https://github.com/jackyzha0/quartz.git --branch v4
   cd quartz

   （如果你想直接用最新开发版，可以省略 --branch v4，但 v4 分支更稳定）

4. 安装依赖：

   npm install

5. 启动本地预览（测试是否正常）：

   npx quartz build --serve

   浏览器打开 http://localhost:8080 ，应该能看到 Quartz 默认示例页面。

步骤 3：把你的 Obsidian 笔记连接到 Quartz

推荐方式 A：最简单（复制笔记）（适合大多数人）

1. 在 Quartz 根目录下找到 content 文件夹（里面已经有示例文件）
2. 把你想公开的 Obsidian 笔记 复制到 content 文件夹中
   • 可以直接拖拽文件夹
   • 保持 Obsidian 的相对路径结构（比如有子文件夹就保留）

方式 B：保持独立 Obsidian vault（进阶，推荐长期使用）

1. 打开 Obsidian → 打开你现有的 vault

2. 找到 vault 的真实路径（右下角小齿轮 → “打开文件夹作为 vault” 右键 → “在文件资源管理器中显示”）

3. 在 Quartz 项目根目录运行以下命令（创建符号链接）：

   Windows（管理员模式 PowerShell）：

   New-Item -ItemType SymbolicLink -Path ".\content" -Target "D:\你的ObsidianVault路径"

   Mac/Linux：

   ln -s /path/to/your/obsidian-vault ./content

   （注意：符号链接方式在 Windows 上有时会遇到权限问题，建议先用方式 A）

步骤 4：做最基础的配置

1. 打开 quartz.config.ts 文件（用 VSCode 或任意编辑器）

2. 修改几个关键字段（至少改这几个）：

   export default defineConfig({
     pageTitle: "我的数字花园",           // 网站标题
     baseUrl: "你的用户名.github.io/仓库名", // 重要！例如： username.github.io/notes
     description: "我的 Obsidian 笔记公开版",
     // ... 其他保持默认
   })

   如果你的仓库是 username.github.io（根域名方式），则 baseUrl: "username.github.io"

3. （可选）修改首页 content/_index.md

   ---
   title: 欢迎来到我的数字花园
   ---
   
   这里是我用 Obsidian 记录的思考、学习笔记和碎片知识。
   
   - About Me
   - Recently Updated
   - Tags

步骤 5：创建 GitHub Actions 自动部署

1. 在 Quartz 项目根目录下创建文件夹和文件：

   quartz/
   └── .github/
       └── workflows/
           └── deploy.yml

2. 把下面内容完整复制到 deploy.yml 中（这是 Quartz v4 官方最新推荐配置）：

   name: Deploy Quartz site to GitHub Pages
   
   on:
     push:
       branches:
         - v4
   
   permissions:
     contents: read
     pages: write
     id-token: write
   
   jobs:
     build:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
           with:
             fetch-depth: 0  # Fetch all history for git info
         - name: Setup Pages
           uses: actions/configure-pages@v5
         - name: Setup Node
           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
       runs-on: ubuntu-latest
       environment:
         name: github-pages
         url: ${{ steps.deployment.outputs.page_url }}
       steps:
         - name: Deploy to GitHub Pages
           id: deployment
           uses: actions/deploy-pages@v4

3. 保存文件

步骤 6：推送到 GitHub 并启用 Pages

1. 把本地 Quartz 仓库关联到你刚才创建的 GitHub 仓库：

   git remote add origin https://github.com/你的用户名/你的仓库名.git
   git branch -M v4
   git push -u origin v4

   （第一次推送会要求登录 GitHub，按提示操作）

2. 去 GitHub 仓库页面 → Settings → Pages（左侧菜单）

3. Source 选 GitHub Actions（不是 Branch）

4. 保存

步骤 7：等待构建 & 访问网站

1. 返回仓库首页 → Actions 标签
2. 看到一个叫 “Deploy Quartz site to GitHub Pages” 的 workflow 正在运行（或已完成）
3. 等 1–3 分钟，刷新页面
4. 访问地址：
   • 如果仓库名叫 你的用户名.github.io → https://你的用户名.github.io
   • 否则 → https://你的用户名.github.io/仓库名

步骤 8：日常更新流程（最重要）

1. 在 Obsidian 中写/修改笔记

2. 把修改后的笔记复制到 content 文件夹（或用符号链接自动同步）

3. 回到终端，进入 quartz 目录：

   git add .
   git commit -m "更新了xxx笔记"
   git push

4. 等待 30秒–2分钟 → 网站自动更新

快速检查清单

• Node.js 已安装
• Git 已安装
• 创建了空的 GitHub 仓库
• 克隆了 Quartz v4
• npm install 成功
• 本地 npx quartz build —serve 能看到页面
• 笔记已放入 content/
• quartz.config.ts 里 baseUrl 写对了
• .github/workflows/deploy.yml 已创建
• 第一次 push 到了 v4 分支
• GitHub Pages 设置成了 GitHub Actions

祝部署顺利！

Obsidian 到 Quartz：博客搭建记录

Q: 部署问题

Q: 部署后，io页面显示的是xml？

A: 问题原因：GitHub Pages 部署失败，报错 “Branch ‘v4’ is not allowed to deploy to github-pages due to environment protection rules”。

方案 1：最简单、最推荐（修改 Environment 保护规则）【5分钟搞定】

1. 打开你的仓库 https://github.com/bigdogaaa/bigdogaaa.github.io

2. 点击 Settings（右上角齿轮）

3. 左侧菜单：Environments（环境）

4. 你会看到一个名为 github-pages 的环境，点击它

5. 在 Deployment protection rules（部署保护规则）部分，找到 Allow specific branches only（只允许特定分支）

   • 取消勾选 “Only allow specific branches”（或者把 v4 添加到允许的分支列表中）
   • 推荐：直接关闭这个规则（Remove restriction），因为你自己控制仓库，基本不需要这个保护

6. 保存更改（Save protection rules）

7. 返回 Actions 标签，重新运行最近一次失败的 workflow（点右上角的 Re-run all jobs 或 Re-run failed jobs）

   这次应该就能成功部署了。

Q: 使用软连接将Obsidian自动集成进Squartz的问题

Q: mklink : 无法将“mklink”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。请检查名称的拼写，如果包括路径，请确保路径。

A: mklink 不是 PowerShell 的 cmdlet ； 它是 cmd.exe 内置命令

解决方案：

用 cmd.exe（管理员）

1. Win 键 → 搜索 cmd

2. 右键 → 以管理员身份运行

3. 执行：

cd /d E:\projects\my-quartz-blog mklink /D content "D:\知识库\MyObsidianRepo"

这是最稳妥、最推荐的方式