docs: update ts-config override examples

docs/advanced/making plugins.md

@@ -645,14 +645,21 @@ plugins:
     enabled: true
 ```
 
-Or via TS override in `quartz.ts`:
+For options that require JavaScript callback functions (not expressible in YAML), use the TS override in `quartz.ts`:
 
 ```ts title="quartz.ts (override)"
 import * as ExternalPlugin from "./.quartz/plugins"
+
+ExternalPlugin.MyPlugin({
+  // callback functions or other non-serializable options
+  customFn: (data) => {
     // ...
-transformers: [ExternalPlugin.MyPlugin()]
+  },
+})
 ```
 
+Options set via `quartz.ts` are merged with YAML options at instantiation time, with `quartz.ts` overrides taking precedence.
+
 ### Development Workflow
 
 During plugin development, you'll frequently install and uninstall your plugin to test changes. The following commands help manage this cycle:

docs/configuration.md

@@ -236,7 +236,20 @@ plugins:
 ```
 
 > [!note]
-> For advanced options that require JavaScript (e.g. callback functions), use the TS override in `quartz.ts`. See the plugin-specific documentation for details.
+> 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 * as ExternalPlugin from "./.quartz/plugins"
+>
+> ExternalPlugin.Explorer({
+>   mapFn: (node) => {
+>     node.displayName = node.displayName.toUpperCase()
+>     return node
+>   },
+> })
+> ```
+>
+> Options set in `quartz.ts` are merged with YAML options and take precedence. See the plugin-specific documentation for available callback options.
 
 You can see a list of all plugins and their configuration options [[tags/plugin|here]].
 

docs/features/explorer.md

@@ -63,10 +63,10 @@ For advanced options like custom sort, filter, and map functions, use the TS ove
 
 ```ts title="quartz.ts"
 import { loadQuartzConfig, loadQuartzLayout } from "./quartz/plugins/loader/config-loader"
-import { Explorer } from "@quartz-community/explorer"
+import * as ExternalPlugin from "./.quartz/plugins"
 
 // Advanced: pass callback functions that can't be expressed in YAML
-Explorer({
+ExternalPlugin.Explorer({
   sortFn: (a, b) => {
     /* ... */
   },
@@ -84,6 +84,16 @@ export default config
 export const layout = await loadQuartzLayout()
 ```
 
+> [!info] How overrides work
+> When you call `ExternalPlugin.Explorer({...})` in `quartz.ts`, the options are recorded and merged with the YAML configuration when the component is instantiated during the build. Options set in `quartz.ts` take precedence over those in `quartz.config.yaml`, following this order: `plugin defaults < YAML options < quartz.ts overrides`.
+>
+> If you have two plugins that export the same name (e.g. two different Explorer plugins installed via `--name`), use the `plugins` map to disambiguate:
+>
+> ```ts title="quartz.ts"
+> import * as ExternalPlugin from "./.quartz/plugins"
+> ExternalPlugin.plugins["my-explorer"].Explorer({ mapFn: ... })
+> ```
+
 When passing in your own options, you can omit any or all of these fields if you'd like to keep the default value for that field.
 
 Want to customize it even more?
@@ -119,7 +129,7 @@ Every function you can pass is optional. By default, only a `sort` function will
 
 ```ts title="Default sort function"
 // Sort order: folders first, then files. Sort folders and files alphabetically
-Explorer({
+ExternalPlugin.Explorer({
   sortFn: (a, b) => {
     if ((!a.isFolder && !b.isFolder) || (a.isFolder && b.isFolder)) {
       return a.displayName.localeCompare(b.displayName, undefined, {
@@ -172,7 +182,7 @@ plugins:
 Custom sort functions require the TS override:
 
 ```ts title="quartz.ts (override)"
-Explorer({
+ExternalPlugin.Explorer({
   sortFn: (a, b) => {
     return a.displayName.localeCompare(b.displayName)
   },
@@ -184,7 +194,7 @@ Explorer({
 Using this example, the display names of all `FileNodes` (folders + files) will be converted to full upper case.
 
 ```ts title="quartz.ts (override)"
-Explorer({
+ExternalPlugin.Explorer({
   mapFn: (node) => {
     node.displayName = node.displayName.toUpperCase()
     return node
@@ -201,7 +211,7 @@ Using this example, you can remove elements from your explorer by providing an a
 Note that this example filters on the title but you can also do it via slug or any other field available on `FileTrieNode`.
 
 ```ts title="quartz.ts (override)"
-Explorer({
+ExternalPlugin.Explorer({
   filterFn: (node) => {
     // set containing names of everything you want to filter out
     const omit = new Set(["authoring content", "tags", "advanced"])
@@ -219,7 +229,7 @@ Explorer({
 You can access the tags of a file by `node.data.tags`.
 
 ```ts title="quartz.ts (override)"
-Explorer({
+ExternalPlugin.Explorer({
   filterFn: (node) => {
     // exclude files with the tag "explorerexclude"
     return node.data?.tags?.includes("explorerexclude") !== true
@@ -233,7 +243,7 @@ By default, the explorer will filter out the `tags` folder.
 To override the default filter function, you can set the filter function to `undefined`.
 
 ```ts title="quartz.ts (override)"
-Explorer({
+ExternalPlugin.Explorer({
   filterFn: undefined, // apply no filter function, every file and folder will visible
 })
 ```
@@ -246,19 +256,20 @@ Explorer({
 > and passing it in.
 >
 > ```ts title="quartz.ts"
-> import { ExplorerOptions } from "@quartz-community/explorer/components"
+> import * as ExternalPlugin from "./.quartz/plugins"
+> import type { ExplorerOptions } from "./.quartz/plugins"
 >
-> export const mapFn: ExplorerOptions["mapFn"] = (node) => {
+> const mapFn: ExplorerOptions["mapFn"] = (node) => {
 >   // implement your function here
 > }
-> export const filterFn: ExplorerOptions["filterFn"] = (node) => {
+> const filterFn: ExplorerOptions["filterFn"] = (node) => {
 >   // implement your function here
 > }
-> export const sortFn: ExplorerOptions["sortFn"] = (a, b) => {
+> const sortFn: ExplorerOptions["sortFn"] = (a, b) => {
 >   // implement your function here
 > }
 >
-> Explorer({
+> ExternalPlugin.Explorer({
 >   // ... your other options
 >   mapFn,
 >   filterFn,
@@ -271,7 +282,7 @@ Explorer({
 To add emoji prefixes (📁 for folders, 📄 for files), you could use a map function in `quartz.ts`:
 
 ```ts title="quartz.ts (override)"
-Explorer({
+ExternalPlugin.Explorer({
   mapFn: (node) => {
     if (node.isFolder) {
       node.displayName = "📁 " + node.displayName

docs/plugins/CustomOgImages.md

@@ -40,9 +40,10 @@ plugins:
 For the TS override approach (needed for custom `imageStructure`):
 
 ```ts title="quartz.ts (override)"
+import * as ExternalPlugin from "./.quartz/plugins"
 import { defaultImage } from "./quartz/plugins/emitters/ogImage"
 
-CustomOgImages({
+ExternalPlugin.CustomOgImages({
   colorScheme: "lightMode",
   width: 1200,
   height: 630,

docs/plugins/Explorer.md

@@ -16,11 +16,20 @@ See [[plugins/Explorer]] for detailed usage information.
 
 This plugin accepts the following configuration options:
 
+**YAML options** (in `quartz.config.yaml`):
+
 - `title`: The title of the explorer. Defaults to `Explorer`.
 - `folderClickBehavior`: The behavior when a folder is clicked. Can be `"link"` to navigate or `"collapse"` to toggle. Defaults to `collapse`.
 - `folderDefaultState`: The default state of folders. Can be `"collapsed"` or `"open"`. Defaults to `collapsed`.
 - `useSavedState`: Whether to use local storage to save the state of the explorer. Defaults to `true`.
 
+**TS override options** (in `quartz.ts`, for callback functions that can't be expressed in YAML):
+
+- `sortFn`: Custom sort function for ordering files and folders.
+- `filterFn`: Custom filter function to exclude specific nodes.
+- `mapFn`: Custom map function to transform node properties (e.g. display names).
+- `order`: Array controlling the order of operations. Defaults to `["filter", "map", "sort"]`.
+
 ### Default options
 
 ```yaml title="quartz.config.yaml"
@@ -33,6 +42,21 @@ This plugin accepts the following configuration options:
     useSavedState: true
 ```
 
+### TS override example
+
+```ts title="quartz.ts"
+import * as ExternalPlugin from "./.quartz/plugins"
+
+ExternalPlugin.Explorer({
+  mapFn: (node) => {
+    node.displayName = node.displayName.toUpperCase()
+    return node
+  },
+})
+```
+
+See [[features/explorer#Advanced customization]] for more examples.
+
 ## API
 
 - Category: Component