---
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 可零配置自动部署，省去服务器维护成本