Initial import

2026-07-11 17:08:37 +00:00
commit 03e5f3452b
303 changed files with 43365 additions and 0 deletions
@@ -0,0 +1,49 @@
+---
+title: Authoring Content
+aliases:
+  - "authoring content"
+---
+
+All of the content in your Quartz should go in the `/content` folder. The content for the home page of your Quartz lives in `content/index.md`. If you've followed the [[installation|installation guide]], this folder should already be initialized. Any Markdown in this folder will get processed by Quartz.
+
+It is recommended that you use [Obsidian](https://obsidian.md/) as a way to edit and maintain your Quartz. It comes with a nice editor and graphical interface to preview, edit, and link your local files and attachments.
+
+Got everything set up? Preview your site locally with `npx quartz build --serve`, or see the [[build|build reference]] for more options.
+
+## Syntax
+
+As Quartz uses Markdown files as the main way of writing content, it fully supports Markdown syntax. By default, Quartz also ships with a few syntax extensions like [Github Flavored Markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) (footnotes, strikethrough, tables, tasklists) and [Obsidian Flavored Markdown](https://help.obsidian.md/Editing+and+formatting/Obsidian+Flavored+Markdown) ([[callouts]], [[wikilinks]]).
+
+Additionally, Quartz also allows you to specify additional metadata in your notes called **frontmatter**.
+
+```md title="content/note.md"
+---
+title: Example Title
+draft: false
+tags:
+  - example-tag
+---
+
+The rest of your content lives here. You can use **Markdown** here :)
+```
+
+Some common frontmatter fields that are natively supported by Quartz:
+
+- `title`: Title of the page. If it isn't provided, Quartz will use the name of the file as the title.
+- `description`: Description of the page used for link previews.
+- `permalink`: A custom URL for the page that will remain constant even if the path to the file changes.
+- `aliases`: Other names for this note. This is a list of strings.
+- `tags`: Tags for this note.
+- `draft`: Whether to publish the page or not. This is one way to make [[private pages|pages private]] in Quartz.
+- `date`: A string representing the day the note was published. Normally uses `YYYY-MM-DD` format.
+
+See [[Frontmatter]] for a complete list of frontmatter.
+
+## Syncing your Content
+
+When your Quartz is at a point you're happy with, you can save your changes to GitHub.
+First, make sure you've [[installation#Setting Up Your GitHub Repository|set up your GitHub repository]] and then run `npx quartz sync`.
+
+## Customization
+
+Frontmatter parsing for `title`, `tags`, `aliases` and `cssclasses` is a functionality of the [[Frontmatter]] plugin, `date` is handled by the [[CreatedModifiedDate]] plugin and `description` by the [[Description]] plugin. See the plugin pages for customization options.
@@ -0,0 +1,34 @@
+---
+title: Getting Started
+---
+
+This guide walks you through setting up Quartz from scratch. If you already ran the [[index#🪴 Get Started|quickstart]] on the home page, you can skip ahead to whichever step you're on.
+
+## Prerequisites
+
+You need these tools installed before continuing:
+
+- **[Node.js](https://nodejs.org/) v22 or later** (run `node -v` to check)
+- **npm v10.9.2 or later** (bundled with Node — run `npm -v` to check)
+- **[Git](https://git-scm.com/)** (run `git -v` to check)
+
+> [!warning] Common issues
+>
+> - **Linux**: System packages (`apt install nodejs`) often ship much older versions. Use [nvm](https://github.com/nvm-sh/nvm) or the [NodeSource](https://github.com/nodesource/distributions) repository to get Node.js v22.
+> - **Windows**: When installing Git, make sure **"Git from the command line and also from 3rd-party software"** is selected so that `git` is available in your terminal. If `node -v` or `git -v` shows "command not found", restart your terminal or check your PATH.
+> - **macOS**: The Xcode command-line tools include Git (`xcode-select --install`). For Node.js, [nvm](https://github.com/nvm-sh/nvm) or the [official installer](https://nodejs.org/) both work.
+
+## Setup Steps
+
+Follow these in order:
+
+1. **[[installation|Installation]]** — Get Quartz (via GitHub template or clone), install dependencies, run the setup wizard (`npx quartz create`), install plugins, and preview your site locally
+2. **[[authoring-content|Authoring Content]]** — Write and organize your Markdown notes in the `content/` folder
+3. **[[installation#Setting Up Your GitHub Repository|Push to GitHub]]** — Create a repository and push your site with `npx quartz sync`
+4. **[[hosting|Deploy]]** — Host your site for free on GitHub Pages, Cloudflare, Netlify, or Vercel
+
+## Upgrading & Migrating
+
+- **[[whats-new|What's New in Quartz 5]]** — Overview of new features and changes
+- **[[upgrading|Upgrading Quartz]]** — Keep your Quartz installation up to date
+- **[[migrating|Migrating to Quartz 5]]** — Migrate from Quartz 4 or Quartz 3
@@ -0,0 +1,161 @@
+---
+title: "Installation"
+aliases:
+  - "setting up your GitHub repository"
+---
+
+This page walks you through the full Quartz setup: from getting the source code to previewing your site locally, then pushing it to GitHub.
+
+## 1. Get Quartz
+
+There are two ways to get started. Pick whichever you prefer:
+
+### Option A: Use the GitHub Template (Recommended)
+
+> [!tip] Why this option?
+> Using the template creates your own repository in one click — no need to reconfigure Git remotes later.
+
+1. Go to the [Quartz repository](https://github.com/jackyzha0/quartz) and click **Use this template** → **Create a new repository**
+2. Give your repository a name (e.g. `quartz`, `notes`, `garden`), choose public or private, then click **Create repository**
+3. Clone **your new repository** and enter the folder:
+
+```bash
+git clone https://github.com/<your-username>/<your-repo>.git
+cd <your-repo>
+```
+
+### Option B: Clone Directly
+
+If you don't use GitHub or prefer a manual setup:
+
+```bash
+git clone https://github.com/jackyzha0/quartz.git
+cd quartz
+```
+
+> [!note]
+> With this option, you'll need to [[#Connect Your Local Clone|point the `origin` remote]] to your own repository later when you're ready to publish.
+
+## 2. Install Dependencies
+
+> [!important]
+> Quartz requires **Node.js 22** or later. Check your version with `node -v` and upgrade at [nodejs.org](https://nodejs.org/) if needed.
+
+```bash
+npm i
+```
+
+> [!note]
+> On subsequent clones of your own repository (e.g. on a new machine), use `npm ci` instead for a faster, reproducible install from the lockfile.
+
+## 3. Initialize Your Site
+
+Run the interactive setup wizard:
+
+```bash
+npx quartz create
+```
+
+This will prompt you for:
+
+- A **template** (`default`, `obsidian`, `ttrpg`, `blog`) — pick the one that matches your use case. See [[create#Templates]] for details on each.
+- A **content strategy** — choose how to populate the `content/` folder:
+  - **new**: Start with an empty folder
+  - **copy**: Copy files from an existing folder (e.g. your Obsidian vault)
+  - **symlink**: Link to an existing folder so changes sync automatically
+- A **base URL** — the URL where your site will be deployed (e.g. `mysite.github.io/quartz`). Don't include `https://`.
+- A **link resolution** strategy — how to resolve internal links (`shortest`, `absolute`, or `relative`). Skipped for Obsidian and TTRPG templates.
+
+For non-interactive usage and more details, see the [[create|`quartz create` CLI reference]].
+
+## 4. Install Plugins
+
+The template you chose references community plugins that need to be installed:
+
+```bash
+npx quartz plugin install --from-config
+```
+
+This downloads and builds all plugins listed in `quartz.config.yaml` into `.quartz/plugins/`.
+
+> [!tip]
+> If some plugins fail to build, try refreshing them to their latest versions:
+>
+> ```bash
+> npx quartz plugin install --latest
+> ```
+>
+> See [[troubleshooting#Plugins fail to build on a fresh clone]] for more details.
+
+## 5. Preview Your Site
+
+```bash
+npx quartz build --serve
+```
+
+Your site is now running at `http://localhost:8080`. The dev server watches for file changes and reloads automatically.
+
+At this point you can [[authoring-content|start writing content]] in the `content/` folder. When you're ready to publish, continue below to push your site to GitHub and [[hosting|deploy it]].
+
+---
+
+## Setting Up Your GitHub Repository
+
+> [!note]
+> If you used **Option A** (GitHub Template) in step 1, your repository already exists and `origin` is already set. You can skip straight to [[#Push Your Site]].
+
+To publish your site, you'll need your own GitHub repository. This section is for **Option B** (direct clone) users.
+
+### Create the Repository
+
+Create a new repository on [GitHub.com](https://github.com/new). Do **not** initialize it with a README, license, or `.gitignore` — Quartz already includes these files, and duplicating them will cause merge conflicts on your first push.
+
+![[github-init-repo-options.png]]
+
+Copy the repository URL from the Quick Setup page:
+
+![[github-quick-setup.png]]
+
+### Connect Your Local Clone
+
+Point your local Quartz at your new repository:
+
+```bash
+# Check current remotes
+git remote -v
+
+# Point origin to your repository
+git remote set-url origin REMOTE-URL
+```
+
+> [!tip]
+> You don't need to add an `upstream` remote manually — `npx quartz create` already configured it for you. The upstream remote is used by `npx quartz upgrade` to pull in future Quartz updates.
+
+### Push Your Site
+
+```bash
+npx quartz sync --no-pull
+```
+
+This commits your content and pushes everything to your repository. For subsequent updates, just run:
+
+```bash
+npx quartz sync
+```
+
+> [!hint] Flags and options
+> For full help options, you can run `npx quartz sync --help`.
+>
+> Most of these have sensible defaults but you can override them if you have a custom setup:
+>
+> - `-d` or `--directory`: the content folder. This is normally just `content`
+> - `-v` or `--verbose`: print out extra logging information
+> - `--commit` or `--no-commit`: whether to make a `git` commit for your changes
+> - `--push` or `--no-push`: whether to push updates to your GitHub fork of Quartz
+> - `--pull` or `--no-pull`: whether to try and pull in any updates from your GitHub fork (i.e. from other devices) before pushing
+
+## Next Steps
+
+- **[[authoring-content|Authoring Content]]** — Write and organize your notes
+- **[[hosting|Hosting]]** — Deploy your site to GitHub Pages, Cloudflare, Netlify, or Vercel
+- **[[configuration|Configuration]]** — Customize your site's appearance and behavior
@@ -0,0 +1,228 @@
+---
+title: "Migrating to Quartz 5"
+aliases:
+  - "migrating from Quartz 3"
+  - "migrating from Quartz 4"
+---
+
+This guide covers migrating to Quartz 5 from previous versions. If you're already on Quartz 5 and want to update to the latest version, see [[upgrading|Upgrading Quartz]] instead.
+
+If you're new to Quartz entirely, skip this guide and follow the [[installation|installation guide]] instead.
+
+## Before You Start: Save Your Content
+
+Before switching branches, make sure your content is safe. Switching to v5 will replace the files in your working directory with the v5 codebase, so your v4 content folder won't be visible until you restore it.
+
+Copy your content folder somewhere outside the repo before switching:
+
+```bash
+# macOS / Linux
+cp -r content /tmp/quartz-content
+
+# Windows (PowerShell)
+Copy-Item -Recurse content $env:TEMP\quartz-content
+```
+
+> [!note] Your old branch is preserved
+> Switching branches does **not** delete your v4 (or v3/hugo) branch. You can always switch back with `git checkout v4` to access your old content and configuration.
+
+## Getting the v5 Branch
+
+Whether you're coming from Quartz 4 or Quartz 3, the first step is the same: get the v5 branch onto your machine and push it to your repository.
+
+```bash
+# Add the official Quartz repository as a remote called "upstream" (skip if already set)
+git remote add upstream https://github.com/jackyzha0/quartz.git
+
+# Fetch the v5 branch from the official repository
+git fetch upstream v5
+
+# Create a local v5 branch from the official one
+git checkout -b v5 upstream/v5
+
+# Install dependencies
+npm i
+
+# Push v5 to your GitHub repository
+git push -u origin v5
+```
+
+## Setting Up Your Site
+
+Once you're on v5, run the interactive setup to configure your site and import your content:
+
+```bash
+npx quartz create
+```
+
+This will prompt you for:
+
+- A **template** (`default`, `obsidian`, `ttrpg`, `blog`) — pick the one closest to your old setup. `obsidian` is recommended if you use an Obsidian vault.
+- A **content strategy** — choose "Copy" and point it to your backed-up content folder.
+
+If you skipped the `create` wizard or need to restore your content manually:
+
+```bash
+# macOS / Linux
+cp -r /tmp/quartz-content/* content/
+
+# Windows (PowerShell)
+Copy-Item -Recurse $env:TEMP\quartz-content\* content\
+```
+
+After running `create`, install all plugins referenced in the generated config:
+
+```bash
+npx quartz plugin install --from-config
+```
+
+## What Changed in v5
+
+Quartz 5 introduces a community plugin system that fundamentally changes how plugins and components are managed. Most plugins that were built into Quartz 4 are now standalone community plugins maintained under the [quartz-community](https://github.com/quartz-community) organization.
+
+Key changes:
+
+- **Configuration format**: TypeScript (`quartz.config.ts`, `quartz.layout.ts`) → YAML (`quartz.config.yaml`)
+- **Plugin system**: Plugins are now standalone Git repositories, installed via `npx quartz plugin add`
+- **Import pattern**: Community plugins use `ExternalPlugin.X()` (from `.quartz/plugins`) instead of `Plugin.X()` (from `./quartz/plugins`)
+- **Layout structure**: `quartz.layout.ts` is gone — layout position is now a per-plugin property in `quartz.config.yaml`
+- **Page types**: A new plugin category for page rendering (content, folder, tag pages)
+- **URL casing**: All generated URLs are now lowercased and hyphenated (e.g. `My Notes/Hello World.md` → `/my-notes/hello-world`). In v4, the original casing of file and folder names was preserved in URLs.
+
+### URL Casing and SEO
+
+If your v4 site had URLs with uppercase letters, those URLs will return 404 errors after upgrading to v5. This also affects search engine indexing, since Google treats URLs as [case-sensitive](https://developers.google.com/search/docs/crawling-indexing/url-structure).
+
+The [[AliasRedirects]] plugin (enabled by default) automatically handles this. During build, it detects files whose original path contained uppercase characters and generates redirect pages at the old URLs. These redirect pages include proper SEO signals (`<link rel="canonical">`, `<meta http-equiv="refresh">`, `<meta name="robots" content="noindex">`) so that search engines transfer ranking to the new lowercase URLs.
+
+No manual configuration is needed — the plugin is enabled by default and the case redirect behavior is on by default. If you want to disable it, set `enableCaseRedirects: false` in the plugin options:
+
+```yaml title="quartz.config.yaml"
+plugins:
+  - source: github:quartz-community/alias-redirects
+    enabled: true
+    options:
+      enableCaseRedirects: false
+```
+
+> [!tip] Hosting on Netlify?
+> Netlify automatically lowercases all URLs and issues server-side 301 redirects. If you're hosting on Netlify, the case redirect pages aren't strictly necessary, but they don't hurt either.
+
+> [!note] Most users don't need to worry about these details
+> If you used the default Quartz 4 configuration (or only changed settings that `npx quartz create` prompts for), the setup wizard handles everything. The details below are for users who had custom plugin configurations.
+
+### Plugin Reference Table
+
+Mapping v4 plugin names to v5 equivalents:
+
+| v4                                  | v5                                          | Type                  |
+| ----------------------------------- | ------------------------------------------- | --------------------- |
+| `Plugin.FrontMatter()`              | `ExternalPlugin.NoteProperties()`           | Community             |
+| `Plugin.CreatedModifiedDate()`      | `ExternalPlugin.CreatedModifiedDate()`      | Community             |
+| `Plugin.SyntaxHighlighting()`       | `ExternalPlugin.SyntaxHighlighting()`       | Community             |
+| `Plugin.ObsidianFlavoredMarkdown()` | `ExternalPlugin.ObsidianFlavoredMarkdown()` | Community             |
+| `Plugin.GitHubFlavoredMarkdown()`   | `ExternalPlugin.GitHubFlavoredMarkdown()`   | Community             |
+| `Plugin.CrawlLinks()`               | `ExternalPlugin.CrawlLinks()`               | Community             |
+| `Plugin.Description()`              | `ExternalPlugin.Description()`              | Community             |
+| `Plugin.Latex()`                    | `ExternalPlugin.Latex()`                    | Community             |
+| `Plugin.RemoveDrafts()`             | `ExternalPlugin.RemoveDrafts()`             | Community             |
+| `Plugin.ContentPage()`              | `ExternalPlugin.ContentPage()`              | Community (pageTypes) |
+| `Plugin.FolderPage()`               | `ExternalPlugin.FolderPage()`               | Community (pageTypes) |
+| `Plugin.TagPage()`                  | `ExternalPlugin.TagPage()`                  | Community (pageTypes) |
+| `Plugin.NotFoundPage()`             | `Plugin.PageTypes.NotFoundPageType()`       | Internal (pageTypes)  |
+| `Plugin.ComponentResources()`       | `Plugin.ComponentResources()` (unchanged)   | Internal              |
+| `Plugin.Assets()`                   | `Plugin.Assets()` (unchanged)               | Internal              |
+| `Plugin.Static()`                   | `Plugin.Static()` (unchanged)               | Internal              |
+| `Plugin.AliasRedirects()`           | `ExternalPlugin.AliasRedirects()`           | Community             |
+| `Plugin.ContentIndex()`             | `ExternalPlugin.ContentIndex()`             | Community             |
+
+Component layout mapping:
+
+| v4 Layout                     | v5 Layout                                |
+| ----------------------------- | ---------------------------------------- |
+| `Component.Explorer()`        | `Plugin.Explorer()`                      |
+| `Component.Graph()`           | `Plugin.Graph()`                         |
+| `Component.Search()`          | `Plugin.Search()`                        |
+| `Component.Backlinks()`       | `Plugin.Backlinks()`                     |
+| `Component.Darkmode()`        | `Plugin.Darkmode()`                      |
+| `Component.Footer()`          | `Plugin.Footer()`                        |
+| `Component.TableOfContents()` | `Plugin.TableOfContents()`               |
+| `Component.Head()`            | `Component.Head()` (unchanged, internal) |
+| `Component.Spacer()`          | `Plugin.Spacer()`                        |
+
+## Updating Your CI/CD
+
+Quartz 5 requires plugins to be installed before building. Add a plugin install step and (optionally) caching to your CI pipeline.
+
+Here's the recommended pattern, based on the project's own GitHub Actions:
+
+```yaml
+- name: Cache dependencies
+  uses: actions/cache@v5
+  with:
+    path: ~/.npm
+    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+    restore-keys: |
+      ${{ runner.os }}-node-
+
+- name: Cache Quartz plugins
+  uses: actions/cache@v5
+  with:
+    path: .quartz/plugins
+    key: ${{ runner.os }}-plugins-${{ hashFiles('quartz.lock.json') }}
+    restore-keys: |
+      ${{ runner.os }}-plugins-
+
+- run: npm ci
+
+- name: Install Quartz plugins
+  run: npx quartz plugin install
+
+- name: Build Quartz
+  run: npx quartz build
+```
+
+The plugin cache uses `quartz.lock.json` as the cache key, so plugins are only re-downloaded when the lockfile changes.
+
+For non-GitHub CI providers (Cloudflare, Vercel, Netlify), the build command should be:
+
+```shell
+npx quartz plugin install && npx quartz build
+```
+
+See [[hosting]] for provider-specific setup details.
+
+## Setting Your Default Branch to v5
+
+After verifying your site builds and deploys correctly, update your repository's default branch to `v5`:
+
+1. Go to your repository on GitHub
+2. Navigate to **Settings** → **General**
+3. Under **Default branch**, click the switch icon next to your current default branch
+4. Select `v5` from the dropdown and click **Update**
+5. Confirm the change
+
+This ensures that new clones, pull requests, and GitHub Pages deployments all target v5 by default. Your old v4 branch remains available for reference.
+
+> [!warning] Update your CI triggers
+> If your CI workflow triggers on a specific branch (e.g. `branches: [v4]`), make sure to update it to `v5`. See the [[hosting]] guide for examples.
+
+## Notes for Quartz 3 Users
+
+If you're coming from Quartz 3 (the Hugo-based version), follow the same steps above — get the v5 branch, run `npx quartz create`, and import your content. There is no need to go through Quartz 4 first.
+
+### Key changes from Quartz 3
+
+1. **Hugo is gone**: Quartz now uses a Node-based static-site generation process. No more Go templates or `hugo-obsidian`.
+2. **Full hot-reload**: The development server (`npx quartz build --serve`) re-processes all content on every change.
+3. **JSX instead of Go templates**: Layout components are written in JSX (JavaScript XML), which is significantly easier to customize.
+4. **New plugin system**: See [[configuration#Plugins|Plugins]] for details on the extensible plugin architecture.
+
+### Things to update
+
+- Update your deploy scripts — see the [[hosting]] guide.
+- Ensure your default branch on GitHub is updated to `v5`.
+- [[folder and tag listings|Folder and tag listings]] have changed:
+  - Folder descriptions go under `content/<folder-name>/index.md`
+  - Tag descriptions go under `content/tags/<tag-name>.md`
+- Custom CSS may need updates if you depended on specific HTML hierarchy or class names from Quartz 3.
@@ -0,0 +1,40 @@
+---
+title: "Upgrading Quartz"
+aliases:
+  - upgrading
+---
+
+> [!note]
+> This is specifically a guide for upgrading your Quartz to a more recent update. If you are coming from Quartz 4 or Quartz 3, check out the [[migrating|migration guide]] for more info.
+
+To fetch the latest Quartz updates, simply run
+
+```bash
+npx quartz upgrade
+```
+
+As Quartz uses [git](https://git-scm.com/) under the hood for versioning, upgrading effectively 'pulls' in the updates from the official Quartz GitHub repository. Merge conflicts in `quartz.lock.json` are handled automatically — Quartz backs up your lockfile before pulling and restores it afterward. For other files with local changes that conflict with the updates, you may need to resolve these manually yourself (or, pull manually using `git pull origin upstream`).
+
+> [!hint]
+> Quartz will try to cache your content before upgrading to try and prevent merge conflicts. If you get a conflict mid-merge, you can stop the merge and then run `npx quartz restore` to restore your content from the cache.
+
+If you have the [GitHub desktop app](https://desktop.github.com/), this will automatically open to help you resolve the conflicts. Otherwise, you will need to resolve this in a text editor like VSCode. For more help on resolving conflicts manually, check out the [GitHub guide on resolving merge conflicts](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-using-the-command-line#competing-line-change-merge-conflicts).
+
+To update your installed plugins separately, use:
+
+```bash
+npx quartz plugin install --latest
+```
+
+See the [[upgrade|CLI reference for upgrade]] for more details on available flags.
+
+### Cleaning Up Unused Plugins
+
+If you've removed plugins from your configuration during an upgrade, you can clean up the leftover files:
+
+```bash
+npx quartz plugin prune --dry-run  # preview what would be removed
+npx quartz plugin prune            # remove orphaned plugins
+```
+
+See the [[cli/plugin#prune|plugin prune reference]] for more details.
@@ -0,0 +1,193 @@
+---
+title: "What's New in Quartz 5"
+aliases:
+  - "changelog"
+  - "v5"
+---
+
+Quartz 5 is a ground-up rearchitecture of Quartz focused on extensibility, performance, and Obsidian compatibility. If you're coming from v4, see [[migrating|Migrating to Quartz 5]] for the upgrade path.
+
+## Plugin Ecosystem
+
+The biggest change in v5 is the move to a **community plugin ecosystem**. Plugins are now standalone packages maintained in the [quartz-community](https://github.com/quartz-community) GitHub organization and installed via git:
+
+```bash
+npx quartz plugin add github:quartz-community/explorer
+```
+
+This means:
+
+- **Independent versioning**: Plugins can be updated without upgrading Quartz itself
+- **Community contributions**: Anyone can publish a Quartz plugin
+- **Smaller core**: Quartz core is leaner; features live in plugins
+- **Plugin registry**: Discover plugins via `npx quartz tui` or the [plugin registry](https://github.com/quartz-community/registry)
+
+Over 40 official plugins ship with Quartz, covering everything from search and graph view to encrypted pages and canvas rendering.
+
+## YAML Configuration
+
+Configuration moved from TypeScript (`quartz.config.ts`) to **YAML** (`quartz.config.yaml`):
+
+```yaml title="quartz.config.yaml"
+configuration:
+  pageTitle: My Digital Garden
+  enableSPA: true
+  enablePopovers: true
+  locale: en-US
+  baseUrl: mysite.github.io
+  theme:
+    typography:
+      header: Schibsted Grotesk
+      body: Source Sans Pro
+      code: IBM Plex Mono
+plugins:
+  - source: github:quartz-community/obsidian-flavored-markdown
+    enabled: true
+    order: 30
+  - source: github:quartz-community/explorer
+    enabled: true
+    layout:
+      position: left
+      priority: 50
+```
+
+Benefits:
+
+- **No TypeScript knowledge required** for basic customization
+- **JSON Schema validation** — editors with YAML support show errors inline
+- **Layout defined per-plugin** — each plugin declares its own position and priority
+- **Templates** — `npx quartz create` offers preconfigured templates (default, obsidian, ttrpg, blog)
+
+For advanced options that need JavaScript (callbacks, custom components), the `quartz.ts` override system provides full programmatic control.
+
+## Improved Obsidian Compatibility
+
+Quartz 5 aims for full compatibility with Obsidian's core features:
+
+- **Wikilinks** — all variations including aliases, headings, block references, and pipe escaping in tables
+- **Callouts** — all built-in types, collapsible variants, and nested callouts
+- **Highlights** — `==highlighted text==` syntax
+- **Comments** — `%%hidden comments%%` (inline and block)
+- **Tags** — `#tag` and `#nested/tag` with tag pages
+- **Custom task characters** — `[?]`, `[!]`, `[>]`, etc. preserved as `data-task` attributes
+- **Mermaid diagrams** — rendered with expand button
+- **YouTube and Tweet embeds** — via image syntax
+- **Block references** — `^block-id` with broad character support
+- **Video/audio embeds** — full format support (mp4, webm, ogv, mov, mkv, avi, flac, aac, etc.)
+- **Canvas files** — rendered as interactive, pannable pages via the canvas-page plugin
+- **Obsidian URI links** — marked with CSS class for custom styling
+- **Footnotes** — via the GitHub Flavored Markdown plugin
+
+See [[Obsidian compatibility]] for the full list.
+
+## Page Type System
+
+Quartz 5 introduces **page types** — plugins that define how different kinds of pages are rendered:
+
+- **Content pages** — regular markdown notes
+- **Folder pages** — directory listing pages
+- **Tag pages** — pages listing notes with a given tag
+- **Canvas pages** — interactive JSON Canvas renderings
+- **Bases pages** — database-style views of your content
+
+Each page type can use a different [[layout#Page Frames|page frame]] for fundamentally different HTML structures (three-column, full-width, minimal, etc.).
+
+## Layout System
+
+The layout system is now declarative. Plugins declare their position (`left`, `right`, `beforeBody`, `afterBody`) and priority in the config:
+
+```yaml
+plugins:
+  - source: github:quartz-community/explorer
+    layout:
+      position: left
+      priority: 50
+  - source: github:quartz-community/graph
+    layout:
+      position: right
+      priority: 10
+```
+
+Additional features:
+
+- **Groups** — combine components into flex rows/columns (e.g., toolbar with search + darkmode toggle)
+- **Conditional rendering** — show/hide components based on page properties (`condition: not-index`, `condition: has-tags`)
+- **Display modifiers** — `display: mobile-only` or `display: desktop-only`
+- **Per-page-type overrides** — different layouts for content, folder, tag, and 404 pages
+
+## Performance
+
+- **Parallel processing** — markdown parsing uses a worker pool across all CPU cores
+- **Incremental rebuilds** — watch mode only re-processes changed files
+- **Pre-built plugins** — community plugins ship compiled `dist/` directories, skipping build-from-source on install
+- **SPA routing** — client-side navigation with `micromorph` for instant page transitions
+- **CDN-cached fonts** — Google Fonts with aggressive caching, or fully self-hosted with `fontOrigin: local`
+
+## CLI Improvements
+
+The CLI is simpler and more helpful:
+
+| Command                          | Description                             |
+| -------------------------------- | --------------------------------------- |
+| `npx quartz create`              | Interactive setup wizard with templates |
+| `npx quartz build --serve`       | Build and serve with hot reload         |
+| `npx quartz sync`                | Commit and push to GitHub               |
+| `npx quartz upgrade`             | Pull latest Quartz updates              |
+| `npx quartz plugin install`      | Install plugins from lockfile           |
+| `npx quartz plugin add <source>` | Add a new plugin                        |
+| `npx quartz plugin list`         | List installed plugins                  |
+| `npx quartz plugin prune`        | Remove unused plugins                   |
+
+Other improvements:
+
+- **Node.js version check** — clear error message if running on Node < 22
+- **Port conflict handling** — helpful message when port is already in use
+- **Plugin lockfile** — `quartz.lock.json` pins plugin versions for reproducible builds
+- **Concurrency control** — `--concurrency` flag for memory-constrained environments
+
+## Internationalization
+
+Quartz 5 supports multiple locales out of the box. Set `locale: ja-JP` (or any supported locale) in your config to translate all UI strings — search placeholders, "table of contents", date formatting, and more.
+
+## New Plugins
+
+Plugins new to v5 (not available in v4):
+
+```base
+filters:
+  and:
+    - file.ext == "md"
+    - file.inFolder("plugins")
+    - note["new-in-v5"] == true
+properties:
+  title:
+    displayName: Plugin
+  repository:
+    displayName: Repository
+  description:
+    displayName: Description
+views:
+  - type: table
+    name: New in v5
+    order:
+      - title
+      - repository
+      - description
+    sort:
+      - property: title
+        direction: ASC
+```
+
+## For Plugin Developers
+
+If you built plugins for v4, the development model has changed significantly:
+
+- Plugins are **standalone npm packages** with their own `package.json`, `tsconfig.json`, and build system
+- The **factory function pattern** (inspired by Astro integrations) replaces class-based plugins
+- **`@quartz-community/types`** provides full type safety without depending on the Quartz core
+- **`@quartz-community/utils`** provides shared path, DOM, and language utilities
+- **`@quartz-community/runtime`** provides browser runtime utilities
+- Plugins can ship **components**, **frames**, **stylesheets**, and **client scripts**
+- A **plugin template** is available at [quartz-community/plugin-template](https://github.com/quartz-community/plugin-template)
+
+See [[making plugins]] for the full guide.