Add a guide for root types#20149
Conversation
niegowski
left a comment
niegowski
left a comment
There was a problem hiding this comment.
I'd also mention and show examples for defining the DOM element for root as default div is not the best choice for inline roots as most probably it could be a h1. This is accepted as a different form of RootConfig#element where integrator passes a name or definition of the view/dom element instead of an actual DOM element. More details in RFC and #20146
|
|
||
| ### Allowed content in a block root | ||
|
|
||
| A block root imposes no schema-level content restrictions. It accepts whatever the enabled plugins register: paragraphs, headings, lists, tables, block images, code blocks, and any other block elements, as well as all inline content within those blocks. |
There was a problem hiding this comment.
It does restrict content; for example, it does not allow text directly in the editor root. It also ensures proper document structure. There is probably more on this in the schema deep dive guide.
|
|
||
| You can configure a root to use a different model element via the {@link module:core/editor/editorconfig~RootConfig#modelElement `config.root.modelElement`} option, and set initial root attributes via {@link module:core/editor/editorconfig~RootConfig#modelAttributes `config.root.modelAttributes`}. CKEditor 5 ships with a second built-in root type, `$inlineRoot`, which restricts the root to inline content only - text and inline formatting, but no block elements. This turns the root into a paragraph-like editing area, suitable for document titles, form labels, meta descriptions, and similar single-line fields. For the technical background behind this feature, see the [paragraph-like editor RFC](https://github.com/ckeditor/ckeditor5/issues/19921). | ||
|
|
||
| ## Block root |
There was a problem hiding this comment.
I'm not sure of the naming. Maybe it should be sth like a container? I'm not sure.
| ``` | ||
| </code-switcher> | ||
|
|
||
| The `modelElement` option works with all single-root editor types: `ClassicEditor`, `InlineEditor`, `BalloonEditor`, `BalloonBlockEditor`, and `DecoupledEditor`. |
There was a problem hiding this comment.
It also works for the multi-root editor.
|
|
||
| The `modelElement` option works with all single-root editor types: `ClassicEditor`, `InlineEditor`, `BalloonEditor`, `BalloonBlockEditor`, and `DecoupledEditor`. | ||
|
|
||
| ### Allowed content in an inline root |
There was a problem hiding this comment.
I'd mention the schema with a link to a section in the schema guide.
2 participants
🚀 Summary
Adds a new "Root types" guide to the Getting started / Setup section covering the two built-in root model element types (
$rootand$inlineRoot).📌 Related issues
💡 Additional information
Optional: Notes on decisions, edge cases, or anything helpful for reviewers.
🧾 Checklists
Use the following checklists to ensure important areas were not overlooked.
This does not apply to feature-branch merges.
If an item is not relevant to this type of change, simply leave it unchecked.
Author checklist
Reviewer checklist
t()(if any).