3.7 KiB
3.7 KiB
title, type, tags, date
| title | type | tags | date | ||||
|---|---|---|---|---|---|---|---|
| Building your Quartz | source |
|
2026-03-04 |
Source File
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 笔记发布为公网可访问的静态网站
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 压缩和错误页处理
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
baseUrlto be configured properly in your configuration to work properly." — Quartz 官方文档，部署前必须配置 baseUrl
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 功能依赖此配置
Key Entities
- Quartz：开源静态网站生成器，专注于将 Obsidian 风格的双链笔记发布为静态网站
- Obsidian：本地笔记软件，Quartz 的内容来源
- GitHub Pages：Quartz 推荐的公网托管方案
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)
Contradictions
- 与通用静态网站托管方案（如 Vercel/Netlify）冲突：
- 冲突点：这些平台自动处理 URL 重写，无需手动配置 Web 服务器
- 当前观点：Quartz 支持手动自托管（自行配置 Nginx/Apache/Caddy），提供完全控制权
- 对方观点：使用 Vercel/Netlify 可零配置自动部署，省去服务器维护成本