Auto-sync: 2026-04-28 12:03

wiki/sources/building-your-quartz.md

@@ -2,60 +2,51 @@
 title: "Building your Quartz"
 type: source
 tags:
+  - clippings
   - quartz
   - obsidian
-  - static-site-generator
-  - self-hosting
-date: 2026-03-04
+date: 2026-04-17
 ---
 
 ## Source File
-- [[raw/Home Office/Building your Quartz.md]]
+- [[Home Office/Building your Quartz]]
 
 ## Summary（用中文描述）
-- 核心主题：Quartz 静态网站的本地预览与自托管部署指南
-- 问题域：如何将 Markdown 文件构建为可预览的本地网站，以及如何通过主流 Web 服务器（Nginx/Apache/Caddy）实现公网自托管
-- 方法/机制：Quartz 将 Markdown 文件转换为 HTML/JS/CSSbundle；本地预览通过 `npx quartz build --serve` 启动热重载服务器；自托管需配置 Web 服务器处理无扩展名链接（`try_files $uri $uri.html $uri/`）
-- 结论/价值：Quartz 提供了一套完整的从笔记到静态网站的构建与部署流程，支持多种主流 Web 服务器的自托管方案，适合将 Obsidian 笔记发布为公网可访问的静态网站
+- 核心主题：Quartz 静态网站构建与部署完整指南
+- 问题域：如何将 Obsidian 笔记发布为可公网访问的静态网站
+- 方法/机制：
+  - 本地预览模式：`npx quartz build --serve` 启动热重载预览服务器
+  - 自托管部署：通过 Nginx / Apache / Caddy 等主流 Web 服务器托管生成的 `public/` 目录
+  - 关键技术：利用 `try_files` 指令处理无扩展名 URL（Quartz 生成链接不含 `.html` 后缀）
+- 结论/价值：Quartz 是一个将 Markdown 文件转换为静态网站的工具，生成的 `public/` 目录可部署到任意静态托管平台，Serve 模式仅用于本地预览，生产部署需配置正确的 Web 服务器
 
 ## Key Claims（用中文描述）
-- Quartz 将 Markdown 文件和资源转换为 HTML、JS 和 CSS 文件包（即一个网站）
-- Serve 模式仅用于本地预览，生产环境部署需使用 GitHub Pages 等静态托管服务
-- 静态托管前需正确配置 `baseUrl`，否则 RSS Feed 和 Sitemap 生成功能将无法正常工作
-- 自托管时 Web 服务器必须处理不含 `.html` 扩展名的链接（Quartz 生成此类链接）
-- Nginx 通过 `try_files $uri $uri.html $uri/ =404` 规则处理无扩展名链接
-- Apache 通过 RewriteCond/RewriteRule 组合实现相同功能
-- Caddy 通过 `try_files {path} {path}.html {path}/ =404` 实现，并支持 gzip 压缩和错误页处理
+- Quartz 将 Markdown 文件和资源转换为 HTML、JS、CSS 静态文件（网站）
+- 要发布网站到公网，需要使用托管服务，Quartz 生成的 `public/` 目录可部署到任何支持静态 HTML 的服务
+- 本地 Serve 模式仅用于预览，生产环境应使用专用托管方案
+- 由于 Quartz 生成不含 `.html` 扩展名的链接，Web 服务器需配置 `try_files` 规则来处理 URL 重写
+- 启用 RSS Feed 和 sitemap 功能需要正确配置 `baseUrl`
 
 ## Key Quotes
-> "Serve mode is intended for local previews only. For production workloads, see the page on hosting."
-> — Quartz 官方文档，明确 serve 模式仅用于本地预览
-
-> "Some Quartz features (like RSS Feed and sitemap generation) require `baseUrl` to be configured properly in your configuration to work properly."
-> — Quartz 官方文档，部署前必须配置 baseUrl
+> "Quartz effectively turns your Markdown files and other resources into a bundle of HTML, JS, and CSS files (a website!)." — 核心功能描述
+> "Serve mode is intended for local previews only. For production workloads, see the page on hosting." — Serve 模式用途说明
+> "Since Quartz generates links that do not include the `.html` extension, you need to let your web server know how to deal with it." — 自托管关键配置说明
 
 ## Key Concepts
-- [[Quartz]]：Obsidian 笔记静态网站生成器，将 Markdown 转换为 HTML/JS/CSS bundle
-- [[Static Site Generator]]：静态网站生成器，无需服务器端渲染，直接托管 HTML 文件
-- [[npx quartz build]]：Quartz 构建命令，核心参数包括 `-d/--directory`（内容目录）、`-o/--output`（输出目录）、`--serve`（本地预览）、`--port`（端口）、`--concurrency`（并发数）
-- [[try_files]]：Nginx 指令，按顺序尝试文件、HTML 文件、目录，最后返回 404
-- [[RewriteRule]]：Apache mod_rewrite 模块指令，用于 URL 重写处理无扩展名链接
-- [[baseUrl]]：Quartz 配置项，用于生成正确的绝对 URL，RSS Feed 和 Sitemap 功能依赖此配置
+- [[Static Site Generator]]：Quartz 的本质——将 Markdown 转换为静态 HTML/CSS/JS 网站的工具
+- [[Obsidian Publishing]]：Quartz 作为 Obsidian 笔记发布平台的角色
+- [[try_files Directive]]：Nginx/Caddy 中用于处理无扩展名 URL 的指令，Quartz 自托管必须配置
 
 ## Key Entities
-- [[Quartz]]：开源静态网站生成器，专注于将 Obsidian 风格的双链笔记发布为静态网站
-- [[Obsidian]]：本地笔记软件，Quartz 的内容来源
-- [[GitHub Pages]]：Quartz 推荐的公网托管方案
+- Quartz：开源 Obsidian 发布工具，由 jzhao.xyz 维护
+- Nginx：主流开源 Web 服务器，用于自托管 Quartz 生成的静态网站
+- Apache：另一种主流 Web 服务器，支持 .htaccess 配置 URL 重写
+- Caddy：现代开源 Web 服务器，默认支持 HTTPS，内置静态文件服务
 
 ## Connections
-- [[Obsidian]] — provides content → [[Quartz]]
-- [[Quartz]] — builds to static files → [[Static Site Generator]]
-- [[Quartz]] — local preview → [[npx quartz build --serve]]
-- [[Quartz]] — production deployment → [[GitHub Pages]] / Self-hosting
-- Self-hosting — requires → [[try_files]] (Nginx) / [[RewriteRule]] (Apache) / [[Caddyfile]] (Caddy)
+- [[Obsidian]] ← uses ← [[Building your Quartz]]
+- [[Static Site Generator]] ← implements ← [[Building your Quartz]]
+- [[Obsidian Publishing]] ← extends ← [[Obsidian]]
 
 ## Contradictions
-- 与通用静态网站托管方案（如 Vercel/Netlify）冲突：
-  - 冲突点：这些平台自动处理 URL 重写，无需手动配置 Web 服务器
-  - 当前观点：Quartz 支持手动自托管（自行配置 Nginx/Apache/Caddy），提供完全控制权
-  - 对方观点：使用 Vercel/Netlify 可零配置自动部署，省去服务器维护成本
+- 无已知冲突内容