180 lines
3.7 KiB
Markdown
180 lines
3.7 KiB
Markdown
---
|
|
publish: true
|
|
permalink: /sh/garden/quartz
|
|
title: Quartz
|
|
created: 2026-02-05T09:58:59.615-07:00
|
|
modified: 2026-02-05T12:21:13.918-07:00
|
|
tags:
|
|
- self_hosting
|
|
- digital_gardening
|
|
- static_site
|
|
cssclasses: ""
|
|
---
|
|
|
|
Quartz is a fast, batteries-included static-site generator that transforms Markdown content into fully functional websites. Perfect for publishing [[20-29 HOBBYS/22 SELF HOSTING/22.11 DIGITAL GARDEN/Obsidian]] vaults as digital gardens.
|
|
|
|
## Features
|
|
|
|
- **Obsidian compatibility** — Wikilinks, callouts, backlinks
|
|
- **Full-text search** — Client-side search
|
|
- **Graph view** — Interactive note connections
|
|
- **Popover previews** — Hover to preview linked notes
|
|
- **Fast** — SPA routing, tiny bundles
|
|
- **Customizable** — JSX components, plugin system
|
|
|
|
## Installation
|
|
|
|
Requires Node.js v22+.
|
|
|
|
```bash
|
|
git clone https://github.com/jackyzha0/quartz.git
|
|
cd quartz
|
|
npm i
|
|
npx quartz create
|
|
```
|
|
|
|
Follow the prompts to initialize with your content.
|
|
|
|
## Configuration
|
|
|
|
Main config: `quartz.config.ts`
|
|
|
|
```typescript
|
|
const config: QuartzConfig = {
|
|
configuration: {
|
|
pageTitle: "My Digital Garden",
|
|
enableSPA: true,
|
|
enablePopovers: true,
|
|
analytics: null, // or plausible, umami, etc.
|
|
locale: "en-US",
|
|
baseUrl: "garden.example.com",
|
|
ignorePatterns: ["private", ".obsidian"],
|
|
defaultDateType: "modified",
|
|
theme: {
|
|
cdnCaching: true,
|
|
typography: {
|
|
header: "Schibsted Grotesk",
|
|
body: "Source Sans Pro",
|
|
code: "IBM Plex Mono",
|
|
},
|
|
colors: {
|
|
lightMode: { /* ... */ },
|
|
darkMode: { /* ... */ },
|
|
},
|
|
},
|
|
},
|
|
plugins: { /* ... */ },
|
|
}
|
|
```
|
|
|
|
## Content
|
|
|
|
All content lives in `/content` folder. Home page is `content/index.md`.
|
|
|
|
### Frontmatter
|
|
|
|
```yaml
|
|
---
|
|
title: My Note
|
|
description: A description for previews
|
|
tags:
|
|
- example
|
|
draft: false # true = don't publish
|
|
publish: true # used by Quartz Syncer
|
|
date: 2026-02-05
|
|
---
|
|
```
|
|
|
|
### Supported Syntax
|
|
|
|
- Standard Markdown + GFM (tables, footnotes, task lists)
|
|
- Obsidian wikilinks: `[[Note Name]]`
|
|
- Obsidian callouts: `> [!info]`
|
|
- LaTeX math: `$inline$` and `$$block$$`
|
|
- Syntax highlighting
|
|
|
|
## Building
|
|
|
|
```bash
|
|
# Development (hot reload)
|
|
npx quartz build --serve
|
|
|
|
# Production build
|
|
npx quartz build
|
|
|
|
# Output goes to /public
|
|
```
|
|
|
|
## Syncing Content
|
|
|
|
### Manual
|
|
|
|
```bash
|
|
npx quartz sync
|
|
```
|
|
|
|
### Quartz Syncer Plugin (Recommended)
|
|
|
|
Install the **Quartz Syncer** plugin in [[20-29 HOBBYS/22 SELF HOSTING/22.11 DIGITAL GARDEN/Obsidian]]:
|
|
|
|
1. Install from Community Plugins
|
|
2. Configure Git provider (GitHub, GitLab, etc.)
|
|
3. Set Quartz repo path
|
|
4. Use plugin to selectively publish notes
|
|
|
|
Features:
|
|
- Compiles Dataview queries to static content
|
|
- Diff viewer before publishing
|
|
- Selective publish/update/remove
|
|
- Smart caching
|
|
|
|
## Hosting Options
|
|
|
|
### Self-hosted with [[20-29 HOBBYS/22 SELF HOSTING/22.11 DIGITAL GARDEN/Caddy]]
|
|
|
|
Build locally or via CI, serve `/public` with Caddy.
|
|
|
|
### GitHub Pages
|
|
|
|
Add `.github/workflows/deploy.yml`:
|
|
```yaml
|
|
name: Deploy Quartz
|
|
on:
|
|
push:
|
|
branches: [v4]
|
|
jobs:
|
|
build:
|
|
runs-on: ubuntu-22.04
|
|
steps:
|
|
- uses: actions/checkout@v4
|
|
with:
|
|
fetch-depth: 0
|
|
- uses: actions/setup-node@v4
|
|
with:
|
|
node-version: 22
|
|
- run: npm ci
|
|
- run: npx quartz build
|
|
- uses: actions/upload-pages-artifact@v3
|
|
with:
|
|
path: public
|
|
deploy:
|
|
needs: build
|
|
runs-on: ubuntu-latest
|
|
environment:
|
|
name: github-pages
|
|
steps:
|
|
- uses: actions/deploy-pages@v4
|
|
```
|
|
|
|
### Cloudflare Pages
|
|
|
|
- Build command: `npx quartz build`
|
|
- Output directory: `public`
|
|
- Production branch: `v4`
|
|
|
|
## Resources
|
|
|
|
- Docs: https://quartz.jzhao.xyz/
|
|
- GitHub: https://github.com/jackyzha0/quartz
|
|
- Quartz Syncer: https://github.com/saberzero1/quartz-syncer
|