diff --git a/docs/advanced/creating components.md b/docs/advanced/creating components.md
index 4224f2d96..6a4d57b9a 100644
--- a/docs/advanced/creating components.md	
+++ b/docs/advanced/creating components.md	
@@ -201,6 +201,37 @@ export const layout = await loadQuartzLayout({
 })
 ```
 
+### Receiving YAML Options in Component-Only Plugins
+
+Component plugins that also belong to a processing category (transformer, filter, emitter, page type) receive options through their factory function automatically. However, **component-only plugins** — those whose manifest declares only `"category": ["component"]` — are loaded via side-effect import and don't go through the factory path.
+
+To receive YAML options in a component-only plugin, export an `init` function from your entry point:
+
+```ts title="src/index.ts"
+export function init(options?: Record<string, unknown>): void {
+  // options contains merged defaultOptions + user's YAML options
+  const myFlag = (options?.myFlag as boolean) ?? false
+  // Use options to configure registrations, global state, etc.
+}
+```
+
+Quartz's config-loader calls `init()` after importing the module, passing the merged result of your manifest's `defaultOptions` and the user's `options` from `quartz.config.yaml`. The merge follows the same `{ ...defaultOptions, ...userOptions }` pattern used for processing plugins — user values take precedence.
+
+Declare your defaults in `package.json`:
+
+```json title="package.json"
+{
+  "quartz": {
+    "category": ["component"],
+    "defaultOptions": {
+      "myFlag": false
+    }
+  }
+}
+```
+
+If your plugin does not export `init`, it continues to work as a pure side-effect import — this is fully backward compatible.
+
 ## Internal Components
 
 Quartz also has internal components that provide layout utilities. These live in `quartz/components/` and are primarily used for structural purposes:
diff --git a/docs/advanced/making plugins.md b/docs/advanced/making plugins.md
index 70616c0da..5de51d0a2 100644
--- a/docs/advanced/making plugins.md	
+++ b/docs/advanced/making plugins.md	
@@ -536,3 +536,5 @@ npx quartz plugin prune --dry-run
 ## Component Plugins
 
 For plugins that provide visual components (like Explorer, Graph, Search), see the [[creating components|creating component plugins]] guide.
+
+Component-only plugins (those with `"category": ["component"]` in their manifest) are loaded via side-effect import rather than a factory function. If your component-only plugin needs to receive user options from `quartz.config.yaml`, export an `init(options)` function — see [[creating components#Receiving YAML Options in Component-Only Plugins|receiving YAML options]] for details.