GitHub/quartz
1
0
Fork 2
mirror of https://github.com/jackyzha0/quartz.git synced 2026-03-21 21:45:42 -05:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

docs: touch-ups

Browse Source
This commit is contained in:
saberzero1 2026-03-14 18:03:31 +01:00
parent 068b6b975c
commit cd667b56de
No known key found for this signature in database
7 changed files with 72 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/advanced/architecture.md
View File

@ -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. 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. 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. 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 ## Plugin System

15
docs/advanced/creating components.md
View File

@ -131,6 +131,21 @@ document.addEventListener("nav", () => {
You can also use the `"prenav"` event, which fires before the page is replaced during SPA navigation. 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. It is best practice to track any event handlers via `window.addCleanup` to prevent memory leaks during SPA navigation.
#### Importing Code #### Importing Code

2
docs/features/index.md
View File

@ -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 - [[folder and tag listings]] — Browse notes by folder or tag
- [[recent notes]] — Display recently modified notes - [[recent notes]] — Display recently modified notes
- [[popover previews]] — Hover previews for internal links - [[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 ## Appearance & Reading

72
docs/getting-started/migrating.md
View File

@ -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` - **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`) - **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) - **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`) - **Component references**: In layout files, community components use `Plugin.X()` (from `.quartz/plugins`) instead of `Component.X()` (from `./quartz/components`)
### Step-by-Step Migration ### 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 ```shell
npx quartz plugin add github:quartz-community/explorer npx quartz create --template default --strategy copy --source /path/to/your/content
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
``` ```
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 ```shell
# Only if you used these in v4: npx quartz plugin resolve
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
``` ```
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 #### 2. Update quartz.config.yaml
**Before (v4):** **Before (v4):**
@ -332,13 +319,14 @@ Component layout mapping:
## Migrating from Quartz 3 ## 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 ```bash
git fetch git fetch
git checkout v4 git checkout v4
git pull upstream v4 git pull upstream v4
npm i npm i
npx quartz plugin restore
npx quartz create npx quartz create
``` ```

4
docs/hosting.md
View File

@ -161,7 +161,7 @@ Before deploying to Vercel, a `vercel.json` file is required at the root of the
> [!note] > [!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. > 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. 2. Go to the [Domains - Dashboard](https://vercel.com/dashboard/domains) page in Vercel.
3. Connect the domain to Vercel 3. Connect the domain to Vercel
4. Press "Add" to connect a custom 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. 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. 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. 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 4. Go to the Settings tab and then click Domains in the sidebar

6
docs/layout.md
View File

@ -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. 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). - `layout.groups` defines flex containers (like `toolbar`) that group multiple components into a single row or column. See [[layout-components]] for details.
- `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.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: 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:

36
docs/plugins/index.md
View File

@ -68,20 +68,22 @@ Quartz plugins fall into several categories:
### Components ### Components
| Plugin | Repository | Enabled | Required | Description | | 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. | | [[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. | | [[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. | | [[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. | | [[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. | | [[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. | | [[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. | | [[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. | | [[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. | | [[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. | | [[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. | | [[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.). | | [[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. | | [[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. | | [[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. | | [[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. |