From 984f8ff8db879c5e1a3d6c11bd08fd7277cc540b Mon Sep 17 00:00:00 2001 From: Vadym Samoilenko Date: Fri, 15 May 2026 16:21:03 +0100 Subject: [PATCH] vault backup: 2026-05-15 16:21:03 --- raw/{ => _processed}/plugins__multi-tenant.md | 0 raw/{ => _processed}/plugins__nested-docs.md | 0 wiki/_master-index.md | 2 +- wiki/payloadcms/_index.md | 1 + wiki/payloadcms/plugin-nested-docs.md | 118 ++++++++++++++++++ 5 files changed, 120 insertions(+), 1 deletion(-) rename raw/{ => _processed}/plugins__multi-tenant.md (100%) rename raw/{ => _processed}/plugins__nested-docs.md (100%) create mode 100644 wiki/payloadcms/plugin-nested-docs.md diff --git a/raw/plugins__multi-tenant.md b/raw/_processed/plugins__multi-tenant.md similarity index 100% rename from raw/plugins__multi-tenant.md rename to raw/_processed/plugins__multi-tenant.md diff --git a/raw/plugins__nested-docs.md b/raw/_processed/plugins__nested-docs.md similarity index 100% rename from raw/plugins__nested-docs.md rename to raw/_processed/plugins__nested-docs.md diff --git a/wiki/_master-index.md b/wiki/_master-index.md index e1d822c..5b8ddd1 100644 --- a/wiki/_master-index.md +++ b/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 | diff --git a/wiki/payloadcms/_index.md b/wiki/payloadcms/_index.md index 913034d..1c9a2e7 100644 --- a/wiki/payloadcms/_index.md +++ b/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 | diff --git a/wiki/payloadcms/plugin-nested-docs.md b/wiki/payloadcms/plugin-nested-docs.md new file mode 100644 index 0000000..3e4a5b1 --- /dev/null +++ b/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