[lexical-website] Documentation Update: Add Decorators concept guide

[WilliamK112]

Description

Addresses part of #2845 by adding a dedicated Concepts page for decorators.

The guide now covers:

• when to choose DecoratorNode instead of TextNode or ElementNode
• inline and block decorators
• extension-first node and command registration with LexicalExtensionComposer
• NodeState and serialization guidance
• framework-specific and framework-independent rendering
• DOMImportExtension, named slots, DOMSlot, and advanced DOM ownership

It also links the existing DecoratorNode section in concepts/nodes to the new page and adds the page to the Concepts sidebar.

Test plan

Before

The website had only a short DecoratorNode subsection and no dedicated guide. The first draft also led with the legacy editor-config plus React plug-in registration pattern.

After

The Concepts sidebar contains a dedicated Decorators page. Its example keeps node registration and command behavior in one extension, and the reviewed DOM-import and named-slots guidance uses the current APIs and relative documentation links.

Validation already run on this branch:

• pnpm exec prettier --check packages/lexical-website/docs/concepts/decorators.mdx packages/lexical-website/docs/concepts/nodes.mdx packages/lexical-website/sidebars.js
• pnpm --filter @lexical/website run tsc
• pnpm --filter @lexical/website run build
• pnpm run build
• IGNORE_PEER_DEPENDENCIES=react pnpm -C packages/lexical-website exec docusaurus build

The latest follow-up changes only the reviewed MDX page; CI will rerun the repository checks.

[meta-cla]

Hi @WilliamK112!

Thank you for your pull request and welcome to our community.

Action Required

In order to merge any pull request (code, docs, etc.), we require contributors to sign our Contributor License Agreement, and we don't seem to have one on file for you.

Process

In order for us to review and merge your suggested changes, please sign at https://code.facebook.com/cla. If you are contributing on behalf of someone else (eg your employer), the individual CLA may not be sufficient and your employer may need to sign the corporate CLA.

Once the CLA is signed, our tooling will perform checks and validations. Afterwards, the pull request will be tagged with CLA signed. The tagging process may take up to 1 hour after signing. Please give it that time before contacting us about it.

If you have received this in error or have any questions, please contact us at cla@meta.com. Thanks!

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
lexical	Ready	Preview	Aug 3, 2026 6:06am
lexical-playground	Ready	Preview	Aug 3, 2026 6:06am

[potatowagon]

Reviewed by Navi (Tater Thoughts Bobblehead) on behalf of @potatowagon.

Assessment: LGTM ✅ — Pure documentation addition, well-structured and accurate.

What I checked:

• Content accuracy: The guide correctly describes DecoratorNode behavior — decorate() returning framework-specific values, createDOM() as the host, updateDOM() returning false for stable hosts, inline-by-default semantics. All consistent with the Lexical source.
• Code examples: The VideoNode examples use correct APIs ($insertNodes, createCommand, COMMAND_PRIORITY_EDITOR, useLexicalComposerContext). The NodeState example correctly uses createState, $getState, $setState, and $create — matching the new NodeState/$config protocol from recent PRs.
• Cross-references: Links to /docs/concepts/node-state and the existing DecoratorNode section in nodes.mdx are valid. Sidebar placement (after nodes, before node-replacement) is logical.
• No library code changes — only packages/lexical-website/ files touched.
• No www compat concerns (docs only).

CI status: Vercel previews pass (both website and playground deploy fine). CLA check is failing — author needs to sign the Meta CLA before this can merge.

Minor suggestions (non-blocking):

1. The isInline(): false return type annotation is redundant since the method body already returns false (TypeScript infers it), but it does serve as documentation — fine either way.
2. Consider adding a brief mention of setDecoratorClassNames() for styling the host element, since newcomers often struggle with styling decorator boundaries.

Ready to merge once CLA is signed.

[meta-cla]

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Meta Open Source project. Thanks!

[etrepum]

This is a good start, a few additional things to cover (some of these are unreleased but in main):

• Current lexical convention is to put all configuration and behavior in extensions, not directly in an editor config (which also implies using LexicalExtensionComposer)
• DecoratorNode can be framework independent if the decorate method returns null (the default) and all work happens in createDOM/updateDOM and/or managed by DOMRenderExtension hooks or a mutation listener (HorizontalRuleNode from @lexical/extension is an example of this)
• There's probably other stuff to cover with named slots which adds a lot of potential to DecoratorNode
• DOMImportExtension should be mentioned in preference to importDOM, which will be deprecated eventually because the two import methods can't be used at the same time
• It's an advanced feature, but NodeState can store any kind of data, given a suitable StateValueConfig
• It's also recently possible to use arbitrary DOM inside or around ElementNode with a combination of DOMSlot and something like mutation listeners, like the ReviewExtension and its associated ReviewNode in the playground

[WilliamK112]

Thanks for the detailed pointers. I pushed a follow-up commit (5397663) that tightens the advanced DOM ownership section around the current ReviewExtension / ReviewNode pattern: it now calls out using getDOMSlot() for editable content inside custom UI, while the extension tracks live nodes with a mutation listener and renders the surrounding review UI.

The earlier follow-up already covered the other items you mentioned: extension-first registration, framework-independent decorators via decorate() === null, DOMImportExtension, named slots, and richer NodeState / StateValueConfig usage.

Validation run locally:

• corepack pnpm exec prettier --check packages/lexical-website/docs/concepts/decorators.mdx
• git diff --check
• corepack pnpm -C packages/lexical-website run tsc
• corepack pnpm run build
• IGNORE_PEER_DEPENDENCIES=react corepack pnpm -C packages/lexical-website exec docusaurus build

[WilliamK112]

Hi @etrepum — I've addressed the documentation feedback in a3b220d. Let me know if you need anything else before re-review. Thanks!

[etrepum]

The PR title and description should follow the pull request template

[WilliamK112]

@etrepum Thanks for the detailed review. Commit 48dbc44 replaces the legacy example with a single extension-first implementation, clarifies the import alternatives, fixes the relative link, and updates the PR metadata to the repository template. All four threads are now addressed and CI is green; re-review whenever convenient.