From 5970e4ec4418b6564fecc39082678c7fc1d8032a Mon Sep 17 00:00:00 2001 From: saberzero1 Date: Wed, 11 Mar 2026 18:44:51 +0100 Subject: [PATCH] docs: updated documentation for v5 --- docs/features/Docker Support.md | 6 ++++++ docs/features/OxHugo compatibility.md | 6 +++--- docs/features/Roam Research compatibility.md | 7 ++----- docs/features/SPA Routing.md | 6 ++++++ docs/features/breadcrumbs.md | 2 +- docs/features/comments.md | 6 +++--- docs/features/upcoming features.md | 12 ------------ docs/getting-started/migrating.md | 16 ++++++++-------- docs/plugins/Assets.md | 2 +- docs/plugins/ComponentResources.md | 2 +- docs/plugins/NotFoundPage.md | 1 + docs/plugins/Static.md | 2 +- docs/plugins/index.md | 6 ++++++ 13 files changed, 39 insertions(+), 35 deletions(-) delete mode 100644 docs/features/upcoming features.md diff --git a/docs/features/Docker Support.md b/docs/features/Docker Support.md index a7fb6a259..e64566f80 100644 --- a/docs/features/Docker Support.md +++ b/docs/features/Docker Support.md @@ -1,3 +1,9 @@ +--- +title: "Docker Support" +tags: + - feature +--- + Quartz comes shipped with a Docker image that will allow you to preview your Quartz locally without installing Node. You can run the below one-liner to run Quartz in Docker. diff --git a/docs/features/OxHugo compatibility.md b/docs/features/OxHugo compatibility.md index 1872d8ca8..b5b5f5672 100644 --- a/docs/features/OxHugo compatibility.md +++ b/docs/features/OxHugo compatibility.md @@ -32,10 +32,10 @@ For the TS override approach: ```ts title="quartz.ts (override)" plugins: { transformers: [ - Plugin.FrontMatter({ delims: "+++", language: "toml" }), + ExternalPlugin.FrontMatter({ delims: "+++", language: "toml" }), // ... - Plugin.OxHugoFlavouredMarkdown(), - Plugin.GitHubFlavoredMarkdown(), + ExternalPlugin.OxHugoFlavouredMarkdown(), + ExternalPlugin.GitHubFlavoredMarkdown(), // ... ], } diff --git a/docs/features/Roam Research compatibility.md b/docs/features/Roam Research compatibility.md index 42736184c..67378f095 100644 --- a/docs/features/Roam Research compatibility.md +++ b/docs/features/Roam Research compatibility.md @@ -25,8 +25,8 @@ For the TS override approach: plugins: { transformers: [ // ... - Plugin.RoamFlavoredMarkdown(), - Plugin.ObsidianFlavoredMarkdown(), + ExternalPlugin.RoamFlavoredMarkdown(), + ExternalPlugin.ObsidianFlavoredMarkdown(), // ... ], } @@ -35,9 +35,6 @@ plugins: { > [!warning] > In YAML, plugin execution order is controlled by the `order` field. Ensure `roam` has a lower `order` value than `obsidian-flavored-markdown` so it runs first. -> [!warning] -> In YAML, plugin execution order is controlled by the `order` field. Ensure the `roam` plugin has a lower `order` value than `obsidian-flavored-markdown` so it runs first. - ## Customization This functionality is provided by the [[RoamFlavoredMarkdown]] plugin. See the plugin page for customization options. diff --git a/docs/features/SPA Routing.md b/docs/features/SPA Routing.md index 7e80b9bea..d18aa2168 100644 --- a/docs/features/SPA Routing.md +++ b/docs/features/SPA Routing.md @@ -1,3 +1,9 @@ +--- +title: "SPA Routing" +tags: + - feature +--- + Single-page-app style rendering. This prevents flashes of unstyled content and improves the smoothness of Quartz. Under the hood, this is done by hijacking page navigations and instead fetching the HTML via a `GET` request and then diffing and selectively replacing parts of the page using [micromorph](https://github.com/natemoo-re/micromorph). This allows us to change the content of the page without fully refreshing the page, reducing the amount of content that the browser needs to load. diff --git a/docs/features/breadcrumbs.md b/docs/features/breadcrumbs.md index 3da2d4d13..66785ed47 100644 --- a/docs/features/breadcrumbs.md +++ b/docs/features/breadcrumbs.md @@ -34,7 +34,7 @@ plugins: For the TS override approach: ```ts title="quartz.ts (override)" -Plugin.Breadcrumbs({ +ExternalPlugin.Breadcrumbs({ spacerSymbol: "❯", rootName: "Home", resolveFrontmatterTitle: true, diff --git a/docs/features/comments.md b/docs/features/comments.md index 7b27ecfe1..c588bae72 100644 --- a/docs/features/comments.md +++ b/docs/features/comments.md @@ -33,7 +33,7 @@ After entering both your repository and selecting the discussion category, Giscu ![[giscus-results.png]] -Finally, in `quartz.config.yaml`, edit the `afterBody` field of the `defaults` layout to include the following options but with the values you got from above: +Finally, in `quartz.config.yaml`, add the comments plugin with the following options (using the values you got from above): ```yaml title="quartz.config.yaml" plugins: @@ -63,7 +63,7 @@ export default config export const layout = await loadQuartzLayout({ defaults: { afterBody: [ - Plugin.Comments({ + ExternalPlugin.Comments({ provider: "giscus", options: { repo: "jackyzha0/quartz", @@ -156,7 +156,7 @@ export default config export const layout = await loadQuartzLayout({ defaults: { afterBody: [ - Plugin.Comments({ + ExternalPlugin.Comments({ provider: "giscus", options: { // Other options... diff --git a/docs/features/upcoming features.md b/docs/features/upcoming features.md deleted file mode 100644 index d45ebeda4..000000000 --- a/docs/features/upcoming features.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -draft: true ---- - -## misc backlog - -- static dead link detection -- cursor chat extension -- sidenotes? https://github.com/capnfabs/paperesque -- direct match in search using double quotes -- https://help.obsidian.md/Advanced+topics/Using+Obsidian+URI -- Canvas diff --git a/docs/getting-started/migrating.md b/docs/getting-started/migrating.md index 28eded55e..33a64b4ed 100644 --- a/docs/getting-started/migrating.md +++ b/docs/getting-started/migrating.md @@ -272,7 +272,7 @@ Add `npx quartz plugin restore` to your build pipeline, before `npx quartz build #### 5. Commit and Deploy ```shell -git add quartz.ts quartz.lock.json +git add quartz.config.yaml quartz.lock.json git commit -m "chore: migrate to Quartz 5 plugin system" ``` @@ -342,17 +342,17 @@ When running `npx quartz create`, you will be prompted as to how to initialize y ### Key changes from Quartz 3 -1. **Removing Hugo and `hugo-obsidian`**: Hugo worked well for earlier versions of Quartz but it also made it hard for people outside of the Golang and Hugo communities to fully understand what Quartz was doing under the hood and be able to properly customize it to their needs. Quartz 4 now uses a Node-based static-site generation process which should lead to a much more helpful error messages and an overall smoother user experience. -2. **Full-hot reload**: The many rough edges of how `hugo-obsidian` integrated with Hugo meant that watch mode didn't re-trigger `hugo-obsidian` to update the content index. This lead to a lot of weird cases where the watch mode output wasn't accurate. Quartz 4 now uses a cohesive parse, filter, and emit pipeline which gets run on every change so hot-reloads are always accurate. -3. **Replacing Go template syntax with JSX**: Quartz 3 used [Go templates](https://pkg.go.dev/text/template) to create layouts for pages. However, the syntax isn't great for doing any sort of complex rendering (like [text processing](https://github.com/jackyzha0/quartz/blob/hugo/layouts/partials/textprocessing.html)) and it got very difficult to make any meaningful layout changes to Quartz 3. Quartz 4 uses an extension of JavaScript syntax called JSX which allows you to write layout code that looks like HTML in JavaScript which is significantly easier to understand and maintain. -4. **A new extensible [[configuration]] and [[configuration#Plugins|plugin]] system**: Quartz 3 was hard to configure without technical knowledge of how Hugo's partials worked. Extensions were even hard to make. Quartz 4's configuration and plugin system is designed to be extended by users while making updating to new versions of Quartz easy. +1. **Removing Hugo and `hugo-obsidian`**: Hugo worked well for earlier versions of Quartz but it also made it hard for people outside of the Golang and Hugo communities to fully understand what Quartz was doing under the hood and be able to properly customize it to their needs. Quartz now uses a Node-based static-site generation process which should lead to much more helpful error messages and an overall smoother user experience. +2. **Full-hot reload**: The many rough edges of how `hugo-obsidian` integrated with Hugo meant that watch mode didn't re-trigger `hugo-obsidian` to update the content index. This lead to a lot of weird cases where the watch mode output wasn't accurate. Quartz now uses a cohesive parse, filter, and emit pipeline which gets run on every change so hot-reloads are always accurate. +3. **Replacing Go template syntax with JSX**: Quartz 3 used [Go templates](https://pkg.go.dev/text/template) to create layouts for pages. However, the syntax isn't great for doing any sort of complex rendering (like [text processing](https://github.com/jackyzha0/quartz/blob/hugo/layouts/partials/textprocessing.html)) and it got very difficult to make any meaningful layout changes to Quartz 3. Quartz now uses an extension of JavaScript syntax called JSX which allows you to write layout code that looks like HTML in JavaScript which is significantly easier to understand and maintain. +4. **A new extensible [[configuration]] and [[configuration#Plugins|plugin]] system**: Quartz 3 was hard to configure without technical knowledge of how Hugo's partials worked. Extensions were even hard to make. Quartz 5's configuration and plugin system is designed to be extended by users while making updating to new versions of Quartz easy. ### Things to update - You will need to update your deploy scripts. See the [[hosting]] guide for more details. -- Ensure that your default branch on GitHub is updated from `hugo` to `v4`. +- Ensure that your default branch on GitHub is updated from `hugo` to `v5`. - [[folder and tag listings|Folder and tag listings]] have also changed. - Folder descriptions should go under `content//index.md` where `` is the name of the folder. - Tag descriptions should go under `content/tags/.md` where `` is the name of the tag. -- Some HTML layout may not be the same between Quartz 3 and Quartz 4. If you depended on a particular HTML hierarchy or class names, you may need to update your custom CSS to reflect these changes. -- If you customized the layout of Quartz 3, you may need to translate these changes from Go templates back to JSX as Quartz 4 no longer uses Hugo. For components, check out the guide on [[creating components]] for more details on this. +- Some HTML layout may not be the same between Quartz 3 and Quartz 5. If you depended on a particular HTML hierarchy or class names, you may need to update your custom CSS to reflect these changes. +- If you customized the layout of Quartz 3, you may need to translate these changes from Go templates back to JSX as Quartz 5 no longer uses Hugo. For components, check out the guide on [[creating components]] for more details on this. diff --git a/docs/plugins/Assets.md b/docs/plugins/Assets.md index 7daa916ea..6915a4926 100644 --- a/docs/plugins/Assets.md +++ b/docs/plugins/Assets.md @@ -16,5 +16,5 @@ This plugin has no configuration options. ## API - Category: Emitter -- Function name: `Plugin.Assets()`. +- Function name: `Plugin.Assets()` (internal plugin). - Source: [`quartz/plugins/emitters/assets.ts`](https://github.com/jackyzha0/quartz/blob/v5/quartz/plugins/emitters/assets.ts). diff --git a/docs/plugins/ComponentResources.md b/docs/plugins/ComponentResources.md index 504e7e703..71625691e 100644 --- a/docs/plugins/ComponentResources.md +++ b/docs/plugins/ComponentResources.md @@ -14,5 +14,5 @@ This plugin has no configuration options. ## API - Category: Emitter -- Function name: `Plugin.ComponentResources()`. +- Function name: `Plugin.ComponentResources()` (internal plugin). - Source: [`quartz/plugins/emitters/componentResources.ts`](https://github.com/jackyzha0/quartz/blob/v5/quartz/plugins/emitters/componentResources.ts). diff --git a/docs/plugins/NotFoundPage.md b/docs/plugins/NotFoundPage.md index 1e0294083..a881e9f6c 100644 --- a/docs/plugins/NotFoundPage.md +++ b/docs/plugins/NotFoundPage.md @@ -14,4 +14,5 @@ This plugin has no configuration options. ## API - Category: Page Type +- Function name: `Plugin.NotFoundPage()` (internal plugin). - Source: [`quartz/plugins/pageTypes/404.ts`](https://github.com/jackyzha0/quartz/blob/v5/quartz/plugins/pageTypes/404.ts) diff --git a/docs/plugins/Static.md b/docs/plugins/Static.md index 604a9c1a9..f1d61c2a0 100644 --- a/docs/plugins/Static.md +++ b/docs/plugins/Static.md @@ -17,5 +17,5 @@ This plugin has no configuration options. ## API - Category: Emitter -- Function name: `Plugin.Static()`. +- Function name: `Plugin.Static()` (internal plugin). - Source: [`quartz/plugins/emitters/static.ts`](https://github.com/jackyzha0/quartz/blob/v5/quartz/plugins/emitters/static.ts). diff --git a/docs/plugins/index.md b/docs/plugins/index.md index 98cf51327..b2112a4cd 100644 --- a/docs/plugins/index.md +++ b/docs/plugins/index.md @@ -4,6 +4,12 @@ title: Plugins Quartz's functionality is provided by a collection of first-party community plugins. Each plugin can be enabled, disabled, and configured via `quartz.config.yaml`. See [[configuration#Plugins|Configuration]] for details on how to manage plugins. +> [!info] Internal vs Community Plugins +> Quartz has two kinds of plugins: +> +> - **Community plugins** are standalone repositories under [`quartz-community`](https://github.com/quartz-community). In TS overrides, they use `ExternalPlugin.X()` (imported from `.quartz/plugins`). +> - **Internal plugins** are built into Quartz core (Assets, Static, ComponentResources, NotFoundPage). In TS overrides, they use `Plugin.X()` (imported from `./quartz/plugins`). + ## Plugin types Quartz plugins fall into several categories: