YAML/TOC-driven hierarchy import for Nested Docs (like Quarto _quarto.yml)

[czargab18]

Feature request: YAML/TOC-driven hierarchy import for Nested Docs (like Quarto _quarto.yml)

Context / Problem

I’m using @payloadcms/plugin-nested-docs to manage hierarchical content (parent/child + breadcrumbs) for documentation-like pages.

Today, the hierarchy is typically created by manually setting the parent relationship for each document in the Admin UI (or by writing custom scripts). This becomes painful for large documentation sites (50–500+ pages), and it’s hard to review hierarchy changes via Git history.

Many documentation tools (e.g. Quarto, MkDocs, Sphinx) solve this by allowing a single, version-controlled YAML file to define the navigation/structure (TOC). Example: Quarto’s _quarto.yml can define the sidebar order and nesting.

Proposal (high-level)

Add an optional YAML-driven hierarchy import/sync mechanism for nested documents. The goal: define the doc tree in one file, and have Payload automatically apply it as parent relationships (and optionally ordering) in the configured collections.

This could be implemented as either:

1. A capability in @payloadcms/plugin-nested-docs itself, or
2. An officially supported utility/CLI/script in the Payload repo (still “first-party” and documented).

Practical example (YAML summary)

Example file: docs/_summary.yml

collection: pages
matchBy: slug # could also support: id | anyFieldName
root:
  - title: Getting Started
    slug: getting-started

  - part: "Unidade I"
    slug: unidade1
    chapters:
      - textuais/unid1/introd.qmd 
        slug: introd
      - textuais/unid1/brasil.qmd 
        slug: brazil

  - part: "Unidade II"
    slug: unidade2
    chapters:
      - textuais/unid2/introd.qmd 

Expected structure in Payload:

• Getting Started
• Guides
  • Installation
  • Configuration
• API Reference

Meaning (data-level):

• pages:guides is parent of pages:installation and pages:configuration
• breadcrumbs update accordingly for all descendants

Desired behavior

Apply relationships from YAML

• Parse YAML and apply:
  • parent links (core requirement)
  • (optional) sibling ordering so the Admin UI/navigation matches YAML order

Matching strategy

• Support matching nodes to documents by:
  • id, or
  • slug, or
  • a custom field configured via matchBy

Safety checks / ergonomics

• Detect duplicates in YAML (same slug/id repeated)
• Detect missing docs (YAML references a slug/id that does not exist)
• Detect orphan docs (docs in collection not present in YAML)
• Prevent cycles (even if YAML is malformed)
• Prefer a dry-run mode:
  • output a diff-like summary of changes (re-parenting, ordering) before applying

Optional: export

• Optionally support “export current hierarchy to YAML” to bootstrap:
  • generate a _summary.yml from current parent tree

Where would this run?

Possible implementations (any one would help a lot):

Option A — CLI command (preferred for CI/CD)

Example:

• payload nested-docs:sync --file docs/_summary.yml --dry-run
• payload nested-docs:sync --file docs/_summary.yml --apply

Benefits:

• Works well with Git-based workflows
• Can be run in CI to validate hierarchy file
• Easier to keep deterministic and auditable

Option B — Utility using Local API (documented / recommended)

Provide an official script example (or helper function) that:

• reads YAML
• resolves docs via Local API
• updates parent
• logs actions and errors

Option C — Admin-only endpoint (less preferred)

• Admin triggers sync via UI button or endpoint
• Still uses YAML as source-of-truth

Why this should be first-party

• Nested Docs already defines the correct semantics (parent, breadcrumbs, cascading updates).
• A standard YAML format would encourage consistency across community projects.
• Enables “docs as code”: review hierarchy changes via PRs instead of manual Admin updates.

Related references

• Nested Docs plugin docs: https://payloadcms.com/docs/plugins/nested-docs
• Nested Docs plugin source: https://github.com/payloadcms/payload/tree/main/packages/plugin-nested-docs
• Quarto TOC/project config: https://quarto.org/docs/reference/projects/books.html#table-of-contents
• MkDocs nav config: https://www.mkdocs.org/user-guide/configuration/#nav

Open questions for maintainers

• Would you prefer this as part of @payloadcms/plugin-nested-docs, or as a separate companion package (e.g. @payloadcms/plugin-docs-toc) that depends on nested-docs?
• Is there an existing recommended approach for “documentation navigation as code” in Payload v4?