From ed0f27c05f27526426983d11ed2d5758f631ed2d Mon Sep 17 00:00:00 2001 From: saberzero1 Date: Sun, 24 May 2026 18:32:05 +0200 Subject: [PATCH] fix: move ExternalPlugin overrides before loadQuartzConfig in quartz.ts docs loadQuartzConfig() internally calls loadQuartzLayout() to build the PageTypeDispatcher, which instantiates components. Plugin option overrides must be registered before this happens. Updated quartz.ts and all doc snippets that show the ExternalPlugin override pattern to place calls before loadQuartzConfig(). Also updated OxHugo and Roam docs from stale v4 plugins pattern to v5 override pattern. --- docs/advanced/making plugins.md | 4 ++-- docs/configuration.md | 7 ++++++- docs/features/OxHugo compatibility.md | 15 +++++---------- docs/features/Roam Research compatibility.md | 13 ++++--------- docs/features/breadcrumbs.md | 1 + docs/plugins/BasesPage.md | 1 + docs/plugins/CustomOgImages.md | 3 ++- docs/plugins/Explorer.md | 1 + 8 files changed, 22 insertions(+), 23 deletions(-) diff --git a/docs/advanced/making plugins.md b/docs/advanced/making plugins.md index ae04695..9f53a59 100644 --- a/docs/advanced/making plugins.md +++ b/docs/advanced/making plugins.md @@ -696,15 +696,15 @@ For options that require JavaScript callback functions (not expressible in YAML) ```ts title="quartz.ts (override)" import * as ExternalPlugin from "./.quartz/plugins" +// Must be placed before loadQuartzConfig() ExternalPlugin.MyPlugin({ - // callback functions or other non-serializable options customFn: (data) => { // ... }, }) ``` -Options set via `quartz.ts` are merged with YAML options at instantiation time, with `quartz.ts` overrides taking precedence. +Options set via `quartz.ts` are merged with YAML options at instantiation time, with `quartz.ts` overrides taking precedence. These calls must be placed **before** `loadQuartzConfig()` in your `quartz.ts`. ### Development Workflow diff --git a/docs/configuration.md b/docs/configuration.md index 9357745..9f434bf 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -242,6 +242,7 @@ plugins: > Some plugin options require JavaScript callback functions (e.g. custom sort, filter, or map functions) that can't be expressed in YAML. For these, use the TS override in `quartz.ts`: > > ```ts title="quartz.ts" +> import { loadQuartzConfig, loadQuartzLayout } from "./quartz/plugins/loader/config-loader" > import * as ExternalPlugin from "./.quartz/plugins" > > ExternalPlugin.Explorer({ @@ -250,9 +251,13 @@ plugins: > return node > }, > }) +> +> const config = await loadQuartzConfig() +> export default config +> export const layout = await loadQuartzLayout() > ``` > -> Options set in `quartz.ts` are merged with YAML options and take precedence. See the plugin-specific documentation for available callback options. +> Options set in `quartz.ts` are merged with YAML options and take precedence. Plugin overrides must be placed **before** `loadQuartzConfig()` so they are applied when components are instantiated during config loading. See the plugin-specific documentation for available callback options. You can see a list of all plugins and their configuration options [[tags/plugin|here]]. diff --git a/docs/features/OxHugo compatibility.md b/docs/features/OxHugo compatibility.md index b5b5f56..6daaffe 100644 --- a/docs/features/OxHugo compatibility.md +++ b/docs/features/OxHugo compatibility.md @@ -27,18 +27,13 @@ plugins: order: 5 ``` -For the TS override approach: +For the TS override approach, place overrides before `loadQuartzConfig()` in `quartz.ts`: ```ts title="quartz.ts (override)" -plugins: { - transformers: [ - ExternalPlugin.FrontMatter({ delims: "+++", language: "toml" }), - // ... - ExternalPlugin.OxHugoFlavouredMarkdown(), - ExternalPlugin.GitHubFlavoredMarkdown(), - // ... - ], -} +import * as ExternalPlugin from "./.quartz/plugins" + +ExternalPlugin.NoteProperties({ delims: "+++", language: "toml" }) +ExternalPlugin.OxHugoFlavouredMarkdown() ``` > [!note] diff --git a/docs/features/Roam Research compatibility.md b/docs/features/Roam Research compatibility.md index 67378f0..ec94205 100644 --- a/docs/features/Roam Research compatibility.md +++ b/docs/features/Roam Research compatibility.md @@ -19,17 +19,12 @@ plugins: order: 30 ``` -For the TS override approach: +For the TS override approach, place overrides before `loadQuartzConfig()` in `quartz.ts`: ```ts title="quartz.ts (override)" -plugins: { - transformers: [ - // ... - ExternalPlugin.RoamFlavoredMarkdown(), - ExternalPlugin.ObsidianFlavoredMarkdown(), - // ... - ], -} +import * as ExternalPlugin from "./.quartz/plugins" + +ExternalPlugin.RoamFlavoredMarkdown() ``` > [!warning] diff --git a/docs/features/breadcrumbs.md b/docs/features/breadcrumbs.md index 66785ed..3bb770d 100644 --- a/docs/features/breadcrumbs.md +++ b/docs/features/breadcrumbs.md @@ -34,6 +34,7 @@ plugins: For the TS override approach: ```ts title="quartz.ts (override)" +// Must be placed before loadQuartzConfig() ExternalPlugin.Breadcrumbs({ spacerSymbol: "❯", rootName: "Home", diff --git a/docs/plugins/BasesPage.md b/docs/plugins/BasesPage.md index 0b5d958..97218e5 100644 --- a/docs/plugins/BasesPage.md +++ b/docs/plugins/BasesPage.md @@ -51,6 +51,7 @@ For custom view renderers, use a TS override in `quartz.ts`: ```ts title="quartz.ts (override)" import * as ExternalPlugin from "./.quartz/plugins" +// Must be placed before loadQuartzConfig() ExternalPlugin.BasesPage({ defaultViewType: "table", customViews: { diff --git a/docs/plugins/CustomOgImages.md b/docs/plugins/CustomOgImages.md index e12267c..4a8d671 100644 --- a/docs/plugins/CustomOgImages.md +++ b/docs/plugins/CustomOgImages.md @@ -43,12 +43,13 @@ For the TS override approach (needed for custom `imageStructure`): import * as ExternalPlugin from "./.quartz/plugins" import { defaultImage } from "./quartz/plugins/emitters/ogImage" +// Must be placed before loadQuartzConfig() ExternalPlugin.CustomOgImages({ colorScheme: "lightMode", width: 1200, height: 630, excludeRoot: false, - imageStructure: defaultImage, // custom JSX component — requires TS + imageStructure: defaultImage, }) ``` diff --git a/docs/plugins/Explorer.md b/docs/plugins/Explorer.md index 3095069..d79c975 100644 --- a/docs/plugins/Explorer.md +++ b/docs/plugins/Explorer.md @@ -47,6 +47,7 @@ This plugin accepts the following configuration options: ```ts title="quartz.ts" import * as ExternalPlugin from "./.quartz/plugins" +// Must be placed before loadQuartzConfig() ExternalPlugin.Explorer({ mapFn: (node) => { node.displayName = node.displayName.toUpperCase()