diff --git a/docs/advanced/architecture.md b/docs/advanced/architecture.md index ddd45d7c7..1bf4b52a9 100644 --- a/docs/advanced/architecture.md +++ b/docs/advanced/architecture.md @@ -48,6 +48,7 @@ This question is best answered by tracing what happens when a user (you!) runs ` 3. Once the page is done loading, the page will then dispatch a custom synthetic browser event `"nav"`. This is used so client-side scripts declared by components can 'setup' anything that requires access to the page DOM. 1. If the [[SPA Routing|enableSPA option]] is enabled in the [[configuration]], this `"nav"` event is also fired on any client-navigation to allow for components to unregister and reregister any event handlers and state. 2. If it's not, we wire up the `"nav"` event to just be fired a single time after page load to allow for consistency across how state is setup across both SPA and non-SPA contexts. + 3. A separate `"render"` event can be dispatched when the DOM is updated in-place without a full navigation (e.g. after content decryption). Components that attach listeners to content elements should listen for both `"nav"` and `"render"`. ## Plugin System diff --git a/docs/advanced/creating components.md b/docs/advanced/creating components.md index af7d6037f..4224f2d96 100644 --- a/docs/advanced/creating components.md +++ b/docs/advanced/creating components.md @@ -131,6 +131,21 @@ document.addEventListener("nav", () => { You can also use the `"prenav"` event, which fires before the page is replaced during SPA navigation. +The `"render"` event fires when the DOM has been updated in-place without a full navigation — for example, after content decryption or dynamic DOM modifications by other plugins. If your component attaches event listeners to content elements, listen for `"render"` in addition to `"nav"` to ensure re-initialization: + +```ts +function setupMyComponent() { + const elements = document.querySelectorAll(".my-interactive") + for (const el of elements) { + el.addEventListener("click", handleClick) + window.addCleanup(() => el.removeEventListener("click", handleClick)) + } +} + +document.addEventListener("nav", setupMyComponent) +document.addEventListener("render", setupMyComponent) +``` + It is best practice to track any event handlers via `window.addCleanup` to prevent memory leaks during SPA navigation. #### Importing Code diff --git a/docs/features/index.md b/docs/features/index.md index 220204e36..38c46f1e9 100644 --- a/docs/features/index.md +++ b/docs/features/index.md @@ -29,6 +29,8 @@ Quartz comes with a wide variety of features out of the box. Most features are p - [[folder and tag listings]] — Browse notes by folder or tag - [[recent notes]] — Display recently modified notes - [[popover previews]] — Hover previews for internal links +- [[StackedPages|stacked pages]] — Andy Matuschak-style stacked sliding panes for tracing note connections +- [[EncryptedPages|encrypted pages]] — Password-protect individual pages with client-side encryption ## Appearance & Reading diff --git a/docs/getting-started/migrating.md b/docs/getting-started/migrating.md index 79edcd12e..518a5ef05 100644 --- a/docs/getting-started/migrating.md +++ b/docs/getting-started/migrating.md @@ -17,61 +17,48 @@ Quartz 5 introduces a community plugin system that fundamentally changes how plu - **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.config.yaml` now uses `defaults` + `byPageType` instead of `sharedPageComponents` + per-layout objects +- **Layout structure**: `quartz.layout.ts` is gone — layout position is now a per-plugin property in `quartz.config.yaml`, with `layout.groups` for flex containers (e.g. toolbar) and `layout.byPageType` for per-page-type overrides - **Page Types**: A new plugin category for page rendering (content, folder, tag pages) - **Component references**: In layout files, community components use `Plugin.X()` (from `.quartz/plugins`) instead of `Component.X()` (from `./quartz/components`) ### Step-by-Step Migration -#### 1. Install Community Plugins +#### 1. Set Up Quartz 5 with a Template -Run the following commands to install the default set of community plugins: +The easiest way to migrate is to use `npx quartz create`, which generates a complete `quartz.config.yaml` from a template with all default plugins pre-configured: ```shell -npx quartz plugin add github:quartz-community/explorer -npx quartz plugin add github:quartz-community/graph -npx quartz plugin add github:quartz-community/search -npx quartz plugin add github:quartz-community/backlinks -npx quartz plugin add github:quartz-community/table-of-contents -npx quartz plugin add github:quartz-community/article-title -npx quartz plugin add github:quartz-community/tag-list -npx quartz plugin add github:quartz-community/page-title -npx quartz plugin add github:quartz-community/darkmode -npx quartz plugin add github:quartz-community/content-meta -npx quartz plugin add github:quartz-community/footer -npx quartz plugin add github:quartz-community/content-page -npx quartz plugin add github:quartz-community/folder-page -npx quartz plugin add github:quartz-community/tag-page -npx quartz plugin add github:quartz-community/created-modified-date -npx quartz plugin add github:quartz-community/syntax-highlighting -npx quartz plugin add github:quartz-community/obsidian-flavored-markdown -npx quartz plugin add github:quartz-community/github-flavored-markdown -npx quartz plugin add github:quartz-community/crawl-links -npx quartz plugin add github:quartz-community/description -npx quartz plugin add github:quartz-community/latex -npx quartz plugin add github:quartz-community/remove-draft -npx quartz plugin add github:quartz-community/alias-redirects -npx quartz plugin add github:quartz-community/content-index -npx quartz plugin add github:quartz-community/favicon -npx quartz plugin add github:quartz-community/og-image -npx quartz plugin add github:quartz-community/cname +npx quartz create --template default --strategy copy --source /path/to/your/content ``` -Also install any optional plugins you were using: +Available templates: `default`, `obsidian`, `ttrpg`, `blog`. Pick the one closest to your setup — `obsidian` is recommended if you use an Obsidian vault. + +> [!tip] Choosing a template +> Each template comes with all 30+ default plugins pre-configured. The main differences are content strategy (OFM support, link resolution) and optional plugins (comments, maps). You can customize everything in `quartz.config.yaml` afterward. + +After running `create`, install all the plugins referenced in the generated config: ```shell -# Only if you used these in v4: -npx quartz plugin add github:quartz-community/comments -npx quartz plugin add github:quartz-community/reader-mode -npx quartz plugin add github:quartz-community/breadcrumbs -npx quartz plugin add github:quartz-community/recent-notes -npx quartz plugin add github:quartz-community/hard-line-breaks -npx quartz plugin add github:quartz-community/citations -npx quartz plugin add github:quartz-community/ox-hugo -npx quartz plugin add github:quartz-community/roam -npx quartz plugin add github:quartz-community/explicit-publish +npx quartz plugin resolve ``` +This reads your `quartz.config.yaml` and installs every plugin listed in it. No need to run 30 individual `npx quartz plugin add` commands. + +> [!note] Custom or optional plugins +> If you used optional plugins in v4 (comments, reader-mode, breadcrumbs, recent-notes, citations, etc.), add them after the initial setup: +> +> ```shell +> npx quartz plugin add github:quartz-community/comments +> npx quartz plugin add github:quartz-community/reader-mode +> npx quartz plugin add github:quartz-community/breadcrumbs +> npx quartz plugin add github:quartz-community/recent-notes +> ``` +> +> See [[plugins/index|Plugins]] for the full list of available community plugins. + +> [!info] Alternative: Use `npx quartz migrate` +> If you have an existing `quartz.config.ts` and `quartz.layout.ts` from v4, you can run `npx quartz migrate` instead. This reads your old config files and generates `quartz.config.yaml` with your existing settings. You'll still need to run `npx quartz plugin resolve` afterward to install the plugins. See [[cli/migrate|quartz migrate]] for details. + #### 2. Update quartz.config.yaml **Before (v4):** @@ -332,13 +319,14 @@ Component layout mapping: ## Migrating from Quartz 3 -As you already have Quartz locally, you don't need to fork or clone it again. Simply just checkout the v4 branch, install the dependencies, and import your old vault. Then follow the [Quartz 4 migration steps above](#migrating-from-quartz-4) to get to v5. +As you already have Quartz locally, you don't need to fork or clone it again. Simply just checkout the v4 branch, install the dependencies, restore plugins, and import your old vault. Then follow the [Quartz 4 migration steps above](#migrating-from-quartz-4) to get to v5. ```bash git fetch git checkout v4 git pull upstream v4 npm i +npx quartz plugin restore npx quartz create ``` diff --git a/docs/hosting.md b/docs/hosting.md index a19dff714..cc6fcd078 100644 --- a/docs/hosting.md +++ b/docs/hosting.md @@ -161,7 +161,7 @@ Before deploying to Vercel, a `vercel.json` file is required at the root of the > [!note] > If there is something already hosted on the domain, these steps will not work without replacing the previous content. As a workaround, you could use Next.js rewrites or use the next section to create a subdomain. -1. Update the `baseUrl` in `quartz.config.js` if necessary. +1. Update the `baseUrl` in `quartz.config.yaml` if necessary. 2. Go to the [Domains - Dashboard](https://vercel.com/dashboard/domains) page in Vercel. 3. Connect the domain to Vercel 4. Press "Add" to connect a custom domain to Vercel. @@ -173,7 +173,7 @@ Before deploying to Vercel, a `vercel.json` file is required at the root of the Using `docs.example.com` is an example of a subdomain. They're a simple way of connecting multiple deployments to one domain. -1. Update the `baseUrl` in `quartz.config.js` if necessary. +1. Update the `baseUrl` in `quartz.config.yaml` if necessary. 2. Ensure your domain has been added to the [Domains - Dashboard](https://vercel.com/dashboard/domains) page in Vercel. 3. Go to the [Vercel Dashboard](https://vercel.com/dashboard) and select your Quartz project. 4. Go to the Settings tab and then click Domains in the sidebar diff --git a/docs/layout.md b/docs/layout.md index 21aa30f12..31bfea790 100644 --- a/docs/layout.md +++ b/docs/layout.md @@ -4,10 +4,10 @@ title: Layout Certain emitters may also output [HTML](https://developer.mozilla.org/en-US/docs/Web/HTML) files. To enable easy customization, these emitters allow you to fully rearrange the layout of the page. -In v5, the layout is defined in `quartz.config.yaml` using a `defaults` + `byPageType` structure. +In v5, the layout is defined in `quartz.config.yaml`. Each plugin controls its own layout position via `layout.position` and `layout.priority` fields. The top-level `layout` section provides two additional mechanisms: -- `defaults` contains layout components shared across ALL page types (head, header, afterBody, footer). -- `byPageType` contains per-page-type overrides (content, folder, tag, 404) for beforeBody, left, right sections, and optionally a `template` to control the page's [[#Page Frames|page frame]]. +- `layout.groups` defines flex containers (like `toolbar`) that group multiple components into a single row or column. See [[layout-components]] for details. +- `layout.byPageType` contains per-page-type overrides (content, folder, tag, 404) for beforeBody, left, right sections, and optionally a `template` to control the page's [[#Page Frames|page frame]]. Each page is composed of multiple different sections which contain `QuartzComponents`. The following code snippet lists all of the valid sections that you can add components to: diff --git a/docs/plugins/index.md b/docs/plugins/index.md index b2112a4cd..14bfca989 100644 --- a/docs/plugins/index.md +++ b/docs/plugins/index.md @@ -68,20 +68,22 @@ Quartz plugins fall into several categories: ### Components -| Plugin | Repository | Enabled | Required | Description | -| ------------------------------ | ------------------------------------------------------------------------------------- | :-----: | :------: | ------------------------------------------- | -| [[ArticleTitle]] | [`quartz-community/article-title`](https://github.com/quartz-community/article-title) | ✅ | ❌ | Renders the article title as an h1 heading. | -| [[ContentMeta]] | [`quartz-community/content-meta`](https://github.com/quartz-community/content-meta) | ✅ | ❌ | Displays creation date and reading time. | -| [[TagList]] | [`quartz-community/tag-list`](https://github.com/quartz-community/tag-list) | ❌ | ❌ | Renders tags as clickable links. | -| [[PageTitle]] | [`quartz-community/page-title`](https://github.com/quartz-community/page-title) | ✅ | ❌ | Renders the site title as a home link. | -| [[darkmode\|Darkmode]] | [`quartz-community/darkmode`](https://github.com/quartz-community/darkmode) | ✅ | ❌ | Toggle between light and dark themes. | -| [[reader mode\|Reader Mode]] | [`quartz-community/reader-mode`](https://github.com/quartz-community/reader-mode) | ✅ | ❌ | Distraction-free reading mode toggle. | -| [[explorer\|Explorer]] | [`quartz-community/explorer`](https://github.com/quartz-community/explorer) | ✅ | ❌ | File tree explorer sidebar. | -| [[graph view\|Graph View]] | [`quartz-community/graph`](https://github.com/quartz-community/graph) | ✅ | ❌ | Interactive link graph visualization. | -| [[full-text search\|Search]] | [`quartz-community/search`](https://github.com/quartz-community/search) | ✅ | ❌ | Full-text search functionality. | -| [[backlinks\|Backlinks]] | [`quartz-community/backlinks`](https://github.com/quartz-community/backlinks) | ✅ | ❌ | Shows pages that link to the current page. | -| [[breadcrumbs\|Breadcrumbs]] | [`quartz-community/breadcrumbs`](https://github.com/quartz-community/breadcrumbs) | ✅ | ❌ | Breadcrumb navigation trail. | -| [[comments\|Comments]] | [`quartz-community/comments`](https://github.com/quartz-community/comments) | ❌ | ❌ | Comment system integration (Giscus, etc.). | -| [[Footer]] | [`quartz-community/footer`](https://github.com/quartz-community/footer) | ✅ | ❌ | Page footer with configurable links. | -| [[recent notes\|Recent Notes]] | [`quartz-community/recent-notes`](https://github.com/quartz-community/recent-notes) | ❌ | ❌ | Displays a list of recently modified notes. | -| [[Spacer]] | [`quartz-community/spacer`](https://github.com/quartz-community/spacer) | ✅ | ❌ | Flexible spacer for layout groups. | +| Plugin | Repository | Enabled | Required | Description | +| ------------------------------ | ----------------------------------------------------------------------------------------- | :-----: | :------: | ------------------------------------------- | +| [[ArticleTitle]] | [`quartz-community/article-title`](https://github.com/quartz-community/article-title) | ✅ | ❌ | Renders the article title as an h1 heading. | +| [[ContentMeta]] | [`quartz-community/content-meta`](https://github.com/quartz-community/content-meta) | ✅ | ❌ | Displays creation date and reading time. | +| [[TagList]] | [`quartz-community/tag-list`](https://github.com/quartz-community/tag-list) | ❌ | ❌ | Renders tags as clickable links. | +| [[PageTitle]] | [`quartz-community/page-title`](https://github.com/quartz-community/page-title) | ✅ | ❌ | Renders the site title as a home link. | +| [[darkmode\|Darkmode]] | [`quartz-community/darkmode`](https://github.com/quartz-community/darkmode) | ✅ | ❌ | Toggle between light and dark themes. | +| [[reader mode\|Reader Mode]] | [`quartz-community/reader-mode`](https://github.com/quartz-community/reader-mode) | ✅ | ❌ | Distraction-free reading mode toggle. | +| [[explorer\|Explorer]] | [`quartz-community/explorer`](https://github.com/quartz-community/explorer) | ✅ | ❌ | File tree explorer sidebar. | +| [[graph view\|Graph View]] | [`quartz-community/graph`](https://github.com/quartz-community/graph) | ✅ | ❌ | Interactive link graph visualization. | +| [[full-text search\|Search]] | [`quartz-community/search`](https://github.com/quartz-community/search) | ✅ | ❌ | Full-text search functionality. | +| [[backlinks\|Backlinks]] | [`quartz-community/backlinks`](https://github.com/quartz-community/backlinks) | ✅ | ❌ | Shows pages that link to the current page. | +| [[breadcrumbs\|Breadcrumbs]] | [`quartz-community/breadcrumbs`](https://github.com/quartz-community/breadcrumbs) | ✅ | ❌ | Breadcrumb navigation trail. | +| [[comments\|Comments]] | [`quartz-community/comments`](https://github.com/quartz-community/comments) | ❌ | ❌ | Comment system integration (Giscus, etc.). | +| [[Footer]] | [`quartz-community/footer`](https://github.com/quartz-community/footer) | ✅ | ❌ | Page footer with configurable links. | +| [[recent notes\|Recent Notes]] | [`quartz-community/recent-notes`](https://github.com/quartz-community/recent-notes) | ❌ | ❌ | Displays a list of recently modified notes. | +| [[Spacer]] | [`quartz-community/spacer`](https://github.com/quartz-community/spacer) | ✅ | ❌ | Flexible spacer for layout groups. | +| [[EncryptedPages]] | [`quartz-community/encrypted-pages`](https://github.com/quartz-community/encrypted-pages) | ✅ | ❌ | Password-protected encrypted pages. | +| [[StackedPages]] | [`quartz-community/stacked-pages`](https://github.com/quartz-community/stacked-pages) | ✅ | ❌ | Andy Matuschak-style stacked sliding panes. |