62 lines
3.7 KiB
Markdown
62 lines
3.7 KiB
Markdown
---
|
||
title: "Building your Quartz"
|
||
type: source
|
||
tags:
|
||
- quartz
|
||
- obsidian
|
||
- static-site-generator
|
||
- self-hosting
|
||
date: 2026-03-04
|
||
---
|
||
|
||
## Source File
|
||
- [[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 笔记发布为公网可访问的静态网站
|
||
|
||
## 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 `baseUrl` to 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 可零配置自动部署，省去服务器维护成本
|