Quartz 发布流程

记录 Obsidian 笔记到博客网站的完整发布链路。

架构概览

Obsidian Vault
    ├── _posts/          ← 技术文章存放目录
    │       ├── B_Code/
    │       ├── A_OS/
    │       └── ...
    └── 其他目录...

           ↑ 软链接 (Symbolic Link)
           │
quartz/content/         ← Quartz 内容源（软链接指向 _posts/）

           ↑ npx quartz build
           │
quartz/public/           ← 静态网站输出

           ↑ deploy 脚本
           │
public/                  ← Hexo 发布目录

           ↓
GitHub Pages             ← 最终托管

核心机制：软链接

Quartz 默认扫描 ./content/ 目录。

通过在 quartz/ 目录下创建指向 _posts/ 的软链接：

# quartz/content/  →  Obsidian Vault 中的 _posts/ 目录
mklink /J quartz\content source\_posts

好处：

• Obsidian 编辑和博客发布完全隔离，互不干扰
• 不需要复制文件，文章在 Obsidian 中更新后，下次构建自动生效
• 保持单点维护——同一份 Markdown，多处可用

构建流程

1. Obsidian 中编辑

在 _posts/ 下创建或修改 .md 文件：

---
title: 文章标题
date: 2026-05-20
tags: [Tag1, Tag2]
---
 
正文内容...

2. 触发构建

cd quartz
npx quartz build

Quartz 会：

1. 扫描 content/（即 _posts/ 的软链接）
2. 按目录结构生成页面路由
3. 应用 Obsidian Flavored Markdown 解析
4. 输出静态 HTML 到 public/

3. 部署到 GitHub Pages

deploy-quartz-to-hexo.bat

该脚本：

1. 执行 npx quartz build
2. 清空 public/ 目录
3. 复制 quartz/public/* 到 public/
4. GitHub Actions 自动部署 public/ 到 Pages

URL 生成规则

Quartz 根据文件路径生成 URL：

_posts/B_Code/CSharp/AppDomain.md
  →  https://yourdomain.com/posts/B_Code/CSharp/AppDomain.html

slug 规则：

• 空格 → -
• 中文 → URL 编码或拼音
• 特殊字符 → 移除

Obsidian 与博客的边界

内容	存放位置
技术文章（博客发布）	_posts/
草稿/待整理	_drafts/
日记/工作记录	_drafts/diary/
小红书内容	XiaoHong/
内部笔记	notes/

_posts/ 会被 Quartz 编译发布，其他目录仅供个人查阅。

注意事项

重命名文件

通过 Obsidian 重命名（Ctrl+R）而非文件系统直接改名——这样可以确保附件目录同步更新。

frontmatter 必填字段

Quartz 依赖以下 frontmatter 字段：

---
title: 文章标题      # 必须，否则使用文件名
date: 2026-05-20   # 自动从文件系统或 git 获取
tags: []           # 生成标签页
---

ignorePatterns

在 quartz.config.ts 中，_posts、_drafts 等目录被排除在 Obsidian vault 根目录扫描之外，仅通过软链接访问。这确保了：

• Obsidian 的文件浏览器不混乱
• Quartz 只编译预期的文章目录
• 软链接的存在对两边都是透明的

相关链接

• Quartz 官方文档
• Obsidian 官方