vault backup: 2026-05-15 16:21:03

wiki/_master-index.md

@@ -35,7 +35,7 @@ This 3-hop pattern works for hundreds of articles without vector search.
 | [[wiki/reports/_index\|reports/]] | Weekly and monthly summaries — generate: `uv run python scripts/report-generator.py --weekly` | 1 |
 | [[wiki/infrastructure/_index\|infrastructure/]] | Server inventory: all 10 SSH hosts — optical, optical-dev, optical-prod, baic, librechat, modocmms, box-cli, aimpress, pve | 12 |
 | [[wiki/testing/_index\|testing/]] | Web app testing: functional, performance, security, UI types; TDD/BDD/Agile methodologies; Selenium/Cypress/Playwright/JMeter/OWASP ZAP tools | 1 |
-| [[wiki/payloadcms/_index\|payloadcms/]] | Full Payload CMS reference — getting started, config, database (Postgres/MongoDB/SQLite), all 22 field types, access control, hooks, authentication (cookies, JWT, API keys, custom strategies, token data), admin UI, custom components, Lexical rich text, live preview, versions/drafts, Local/REST/GraphQL APIs, queries, plugins, jobs queue, upload, ecommerce, production deploy, TypeScript, migration guides, i18n, localization, hierarchy | 116 |
+| [[wiki/payloadcms/_index\|payloadcms/]] | Full Payload CMS reference — getting started, config, database (Postgres/MongoDB/SQLite), all 22 field types, access control, hooks, authentication (cookies, JWT, API keys, custom strategies, token data), admin UI, custom components, Lexical rich text, live preview, versions/drafts, Local/REST/GraphQL APIs, queries, plugins, jobs queue, upload, ecommerce, production deploy, TypeScript, migration guides, i18n, localization, hierarchy | 117 |
 
 | [[wiki/shared-patterns/_index\|shared-patterns/]] | Oliver Agency standard library patterns: httpx, structlog, pydantic-settings, alembic — reuse before writing from scratch | 4 |
 | [[wiki/mistakes/_index\|mistakes/]] | Anti-patterns extracted from sessions — per-stack running lists (fastapi, react, docker, postgres, general) — injected at session start | 5 |

wiki/payloadcms/_index.md

@@ -118,3 +118,4 @@
 | [[wiki/payloadcms/plugin-import-export\|Import/Export Plugin]] | CSV/JSON import-export via admin UI or API: jobs queue setup, import modes (create/update/upsert), batch hooks, column mapping, access control warning | raw/plugins__import-export.md | 2026-05-15 |
 | [[wiki/payloadcms/plugin-mcp\|MCP Plugin]] | Expose Payload as an MCP server — API key access control (two-step), custom tools/prompts/resources, token efficiency (select + overrideResponse), Claude Code / Cursor / VS Code client config | raw/plugins__mcp.md | 2026-05-15 |
 | [[wiki/payloadcms/plugin-multi-tenant\|Multi-Tenant Plugin]] | Scaffold multi-tenancy: tenant field on collections, Admin selector, filtered list views + relationship pickers, isGlobal (1 doc/tenant), cascade delete, super-admin bypass, useTenantSelection hook | raw/plugins__multi-tenant.md | 2026-05-15 |
+| [[wiki/payloadcms/plugin-nested-docs\|Nested Docs Plugin]] | Parent/child hierarchy for collections: auto `parent` + `breadcrumbs` fields, recursive cascade updates, `generateURL`/`generateLabel` options, custom field overrides, localization support | raw/plugins__nested-docs.md | 2026-05-15 |

wiki/payloadcms/plugin-nested-docs.md

@@ -0,0 +1,118 @@
+---
+title: "Nested Docs Plugin"
+aliases: [nested-docs, plugin-nested-docs, parent-child-pages]
+tags: [payloadcms, plugin, hierarchy, breadcrumbs, pages]
+sources: [raw/plugins__nested-docs.md]
+created: 2026-05-15
+updated: 2026-05-15
+---
+
+## Overview
+
+`@payloadcms/plugin-nested-docs` adds parent/child hierarchy to any collection. It injects two fields — `parent` (relationship) and `breadcrumbs` (array) — and recursively updates all descendants whenever a parent changes.
+
+Common use case: hierarchical page tree (`/about/company/our-team`).
+
+## Install
+
+```bash
+pnpm add @payloadcms/plugin-nested-docs
+```
+
+## Basic Setup
+
+```ts
+import { nestedDocsPlugin } from '@payloadcms/plugin-nested-docs'
+
+buildConfig({
+  plugins: [
+    nestedDocsPlugin({
+      collections: ['pages'],
+      generateLabel: (_, doc) => String(doc.title),
+      generateURL: (docs) =>
+        docs.reduce((url, doc) => `${url}/${String(doc.slug)}`, ''),
+    }),
+  ],
+})
+```
+
+## Auto-Injected Fields
+
+### `parent`
+- Relationship field pointing to another doc in the same collection
+- Editor picks the direct parent; plugin builds the full ancestry chain
+
+### `breadcrumbs`
+Array of ancestor objects, each with:
+
+| Field | Default | Override via |
+|-------|---------|-------------|
+| `label` | `admin.useAsTitle` or doc ID | `generateLabel` option |
+| `url` | `undefined` | `generateURL` option |
+
+Breadcrumbs cascade automatically — if a grandparent slug changes, every descendant's breadcrumbs update.
+
+## Plugin Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `collections` | `string[]` | Collection slugs to enable |
+| `generateLabel` | `(docs, doc, collection, req) => string` | Dynamic breadcrumb label |
+| `generateURL` | `(docs, doc, collection, req) => string` | Dynamic breadcrumb URL |
+| `parentFieldSlug` | `string` | Use your own `parent` field (must be top-level) |
+| `breadcrumbsFieldSlug` | `string` | Use your own `breadcrumbs` field (must be top-level) |
+
+> **Gotcha:** custom `parent`/`breadcrumbs` fields **must** be at the top level — not inside a `group`, `array`, or `blocks`.
+
+## Field Overrides
+
+Use `createParentField` / `createBreadcrumbsField` to extend the built-in fields:
+
+```ts
+import { createParentField, createBreadcrumbsField } from '@payloadcms/plugin-nested-docs'
+
+fields: [
+  createParentField('pages', {
+    admin: { position: 'sidebar' },
+    // keep self-reference guard: filterOptions: ({ id }) => ({ id: { not_equals: id } })
+  }),
+  createBreadcrumbsField('pages', { label: 'Page Breadcrumbs' }),
+]
+```
+
+> If you override the `name` of either field, set `parentFieldSlug` / `breadcrumbsFieldSlug` in plugin options.
+
+## Localization
+
+When `localization` is enabled in Payload Config, the `breadcrumbs` field is automatically localized. See [[wiki/payloadcms/localization|Localization]].
+
+## TypeScript
+
+```ts
+import type {
+  NestedDocsPluginConfig,
+  GenerateURL,
+  GenerateLabel,
+} from '@payloadcms/plugin-nested-docs/types'
+```
+
+## Key Takeaways
+
+- Plugin injects `parent` + `breadcrumbs` fields; updates cascade recursively down the tree
+- `generateURL` builds full paths like `/about/company/our-team` from breadcrumb docs array
+- Custom fields are supported — set `parentFieldSlug`/`breadcrumbsFieldSlug` and place them **at top-level only**
+- Use `createParentField`/`createBreadcrumbsField` when you need sidebar placement or label overrides
+- Localization is automatic when Payload's `localization` config is set
+- Official Website Template in the Payload repo uses this plugin as a reference
+
+## Related
+
+- [[wiki/payloadcms/hierarchy|Hierarchy — Tree Structure]] — Payload's built-in hierarchy feature (virtual slug/title paths, different approach)
+- [[wiki/payloadcms/plugins|Official Plugins]] — all 10 official plugins overview
+- [[wiki/payloadcms/localization|Localization — Content Internationalization]] — locale config used by breadcrumbs
+- [[wiki/payloadcms/fields-relationship|Relationship Field]] — underlying field type used for `parent`
+
+## Sources
+
+- `raw/plugins__nested-docs.md`
+- https://payloadcms.com/docs/plugins/nested-docs