Nested docs page tree plugin, and a question about reorder history

[CarloBu]

Hello there!

Thank you for Payload CMS. I use it for complex website projects, and its flexibility is one of the main reasons I keep choosing it.

It's awesome cms, but one admin UX problem I keep running into with clients is nested pages. Even slightly complex websites usually have page hierarchies, so @payloadcms/plugin-nested-docs is always part of my setup. The missing piece for editors is a visual page tree and clients are always confused of the published / changed / draft status.

To fill that gap, I have been working on a companion plugin for nested docs:

payload-nested-docs-page-tree

It already does its job, but it has outgrown my initial scope, so I am currently refactoring the plugin. The biggest change is that parent moves and reordering are now separate interactions.

Existing features

Visual hierarchy shading for nested pages

Homepage icon

Live URL path preview

New features

Custom status badges

Better status badges now support custom labels and one base color per status, automatically adapted for both light and dark Payload themes. If colors are not set - plugin uses the payload's default colors - blue,orange,red.

Diagnostics mode

diagnostics: true adds structured logs while debugging page tree behavior.

Orderable-only reorder handle

The reorder drag handle is only shown when the current sort is orderable.

reorder-handle.mp4

Separate parent-move mode

Parent moves are a serious hierarchy change, so the parent-move handle is hidden by default. Editors can enable it with the “Edit Hierarchy” button when they intentionally want to change page hierarchy.

edit-hierarchy.mp4

The parent move behavior is intuitive: drag a page onto another page to make it a child of that page.

parent-move.mp4

To move a page back to the root level, drag it between root pages.

move-to-root.mp4

Internally, the UI calls this plugin’s /:id/move endpoint. That endpoint updates only the nested docs parent field through Payload’s local API, and @payloadcms/plugin-nested-docs continues to handle the parent and breadcrumb behavior through its normal fields and hooks.

Reordering is the more complicated part. The plugin has to allow reordering only within the same parent or root level. It should not allow a reorder drag to change the parent.
https://github.com/user-attachments/assets/e996ca26-03bc-449f-b01e-ea68ec463346

The part I am still looking for a solution on is how to reorder documents without creating document history entries or triggering normal document-change side effects.

Right now, the refactor avoids payload.update() for pure reordering and updates the order key through a lower-level Payload database operation, because reordering is not really content editing. This works, but I would prefer a supported Payload-level API for changing orderable values without creating document history entries or running the same hooks as a content update.

Has anyone solved this cleanly inside the Payload layer? I want to avoid relying on raw database writes if there is an official or recommended way to perform silent orderable reordering.

[CarloBu]

Update:
I published payload-nested-docs-page-tree@1.4.0, and the reorder issue is now solved.

Reordering now uses a dedicated POST /:id/reorder endpoint instead of payload.update(). The endpoint validates that the moved page and target page are under the same parent, then writes a new Payload orderable value through Payload’s DB adapter layer. For draft-enabled collections, it also patches the latest version row in place so the tree order stays in sync without creating a new version entry.

For draft-enabled collections, it also keeps the latest version row in sync, so the admin tree order stays correct without creating a new history entry.
https://github.com/WLF-Studios/payload-nested-docs-page-tree