Add a guide for root types

docs/examples/builds/multi-root-editor.md

@@ -21,7 +21,7 @@ The main difference between using a multi-root editor and using multiple separat
 
 ## Editor example configuration
 
-Check out the {@link getting-started/setup/editor-types#multi-root-editor Editor types} guide to learn more about implementing this kind of editor. You will find implementation steps there. You can see this example editor's code below.
+Check out the {@link getting-started/setup/editor-types#multi-root-editor Editor types} guide to learn more about implementing this kind of editor. You will find implementation steps there. To learn how to configure individual roots to accept different content — for example, an inline-only title alongside a block content body — see the {@link getting-started/setup/root-types Root types} guide. You can see this example editor's code below.
 
 <details>
 <summary>View editor configuration script</summary>

docs/framework/contributing/code-style.md

@@ -1179,7 +1179,7 @@ This rule ensures that changelog entry files are populated with proper data and
 
 ### Disallow hardcoded `$root` literals: `ckeditor5-rules/no-literal-dollar-root`
 
-This rule disallows the literal `'$root'` string anywhere it could be used as a schema context. Hardcoding `'$root'` is silently wrong when {@link module:core/editor/editorconfig~RootConfig#modelElement `config.root.modelElement`} is customized: the runtime root no longer matches the literal, and any schema check or upcast against it operates against the wrong element name.
+This rule disallows the literal `'$root'` string anywhere it could be used as a schema context. Hardcoding `'$root'` is silently wrong when {@link module:core/editor/editorconfig~RootConfig#modelElement `config.root.modelElement`} is customized: the runtime root no longer matches the literal, and any schema check or upcast against it operates against the wrong element name. See the {@link getting-started/setup/root-types Root types} guide for an overview of the available root model element types.
 
 The rule also reports two specific patterns that have a name-agnostic replacement and provides an auto-fix for them:
 

docs/getting-started/setup/editor-types.md

@@ -207,11 +207,9 @@ The multi-root editor is an editor type that features multiple, separate editabl
 	See an {@link examples/builds/multi-root-editor example of the multi-root editor} in action.
 </snippet-footer>
 
-<info-box>
-	At this time, the multi-root editor is not yet available via the [Builder](https://ckeditor.com/ckeditor-5/builder/?redirect=docs).
-</info-box>
+At this time, the multi-root editor is not yet available via the [Builder](https://ckeditor.com/ckeditor-5/builder/?redirect=docs).
 
-<info-box important>
+<info-box>
 	The multi-root editor requires a more advanced configuration of the roots.
 </info-box>
 
@@ -274,3 +272,7 @@ Then, use these roots to place editor windows in the document.
 	</div>
 </div>
 ```
+
+<info-box hint>
+	All editor types support configuring what content a root can hold. This is most useful in multi-root setups, but it works with any editor type. See the {@link getting-started/setup/root-types Root types} guide for details.
+</info-box>

docs/getting-started/setup/root-types.md

@@ -0,0 +1,179 @@
+---
+category: setup
+menu-title: Root types
+meta-title: Root types | CKEditor 5 Documentation
+meta-description: Learn how to configure CKEditor 5 root types to control whether a root accepts block content, inline-only content, or a mix of both.
+order: 27
+modified_at: 2026-05-15
+---
+
+# Root types
+
+In CKEditor 5, a root is the top-level container element in the document model - every editable area has exactly one. The type of that root element determines what content is allowed in that area. By default, roots use the `$root` model element, which accepts block-level content such as paragraphs, headings, lists, and tables.
+
+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
+
+The default root type is `$root`. It accepts the full range of block-level content: paragraphs, headings, lists, tables, block images, and any other block elements that the enabled plugins support. This is the standard editing experience for most use cases - articles, documents, comments, and similar rich-text areas.
+
+### Configuration
+
+You do not need to set `modelElement` explicitly to get this behavior. The following two configurations are equivalent:
+
+```js
+ClassicEditor
+	.create( {
+		attachTo: document.querySelector( '#editor' ),
+		root: {
+			initialData: '<p>Start writing here.</p>'
+		},
+		licenseKey: '<YOUR_LICENSE_KEY>',
+		// ...
+	} )
+	.then( /* ... */ )
+	.catch( /* ... */ );
+```
+
+```js
+ClassicEditor
+	.create( {
+		attachTo: document.querySelector( '#editor' ),
+		root: {
+			initialData: '<p>Start writing here.</p>',
+			modelElement: '$root'
+		},
+		licenseKey: '<YOUR_LICENSE_KEY>',
+		// ...
+	} )
+	.then( /* ... */ )
+	.catch( /* ... */ );
+```
+
+### 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.
+
+## Inline root
+
+A root configured with `$inlineRoot` behaves like a single paragraph: pressing <kbd>Enter</kbd> has no effect, because inserting a new block is not allowed.
+
+### Configuration
+
+To configure any single-root editor type as inline-only, set {@link module:core/editor/editorconfig~RootConfig#modelElement `modelElement`} to `'$inlineRoot'` in the `root` config:
+
+<code-switcher>
+```js
+import { ClassicEditor, Essentials, Bold, Italic } from 'ckeditor5';
+
+ClassicEditor
+	.create( {
+		attachTo: document.querySelector( '#editor' ),
+		root: {
+			initialData: 'My document title',
+			modelElement: '$inlineRoot'
+		},
+		licenseKey: '<YOUR_LICENSE_KEY>',
+		plugins: [ Essentials, Bold, Italic ],
+		toolbar: [ 'bold', 'italic' ]
+	} )
+	.then( /* ... */ )
+	.catch( /* ... */ );
+```
+</code-switcher>
+
+The `modelElement` option works with all single-root editor types: `ClassicEditor`, `InlineEditor`, `BalloonEditor`, `BalloonBlockEditor`, and `DecoupledEditor`.
+
+### Allowed content in an inline root
+
+The `$inlineRoot` model element allows the same content as a paragraph: text nodes and inline objects. Block elements are not permitted.
+
+| Content type                                              | Allowed |
+|-----------------------------------------------------------|---------|
+| Plain text                                                | Yes     |
+| Inline formatting (bold, italic, underline, and similar)  | Yes     |
+| Links                                                     | Yes     |
+| Mentions                                                  | Yes     |
+| Inline images                                             | Yes     |
+| Paragraphs and headings                                   | No      |
+| Lists                                                     | No      |
+| Tables                                                    | No      |
+| Block images                                              | No      |
+
+Plugins that only produce block-level output will have no effect inside an `$inlineRoot` root. You can still include such plugins in your editor setup - they will be inactive when the cursor is inside an inline root, and toolbar items for block-only features will be disabled.
+
+## Mixed root types in multi-root editor
+
+Mixing root types lets different parts of the same document use different content models. In a multi-root editor, you can configure each root independently. For example, a common pattern is to use an inline root for the title and a standard block root for the body:
+
+<code-switcher>
+```js
+import { MultiRootEditor, Essentials, Bold, Italic, Paragraph, Heading } from 'ckeditor5';
+
+MultiRootEditor
+	.create( {
+		roots: {
+			title: {
+				element: document.querySelector( '#title' ),
+				initialData: 'My document title',
+				modelElement: '$inlineRoot'
+			},
+			body: {
+				element: document.querySelector( '#body' ),
+				initialData: '<p>Main content goes here.</p>'
+			}
+		},
+		licenseKey: '<YOUR_LICENSE_KEY>',
+		plugins: [ Essentials, Bold, Italic, Paragraph, Heading ],
+		toolbar: [ 'heading', '|', 'bold', 'italic' ]
+	} )
+	.then( /* ... */ )
+	.catch( /* ... */ );
+```
+</code-switcher>
+
+The `title` root only accepts inline content, while the `body` root accepts the full range of block elements. The toolbar and undo stack are shared between both roots. See {@link getting-started/setup/editor-types#multi-root-editor Editor types} for a broader overview of the multi-root editor.
+
+### Adding roots dynamically
+
+In a multi-root editor, you can add roots at runtime using {@link module:editor-multi-root/multirooteditor~MultiRootEditor#addRoot `editor.addRoot()`}. The `modelElement` option sets the root type, the same way as in the static configuration:
+
+```js
+editor.on( 'addRoot', ( evt, root ) => {
+	const editableElement = editor.createEditable( root );
+
+	document.querySelector( '#editors' ).appendChild( editableElement );
+} );
+
+// Add a block root.
+editor.addRoot( 'section', {
+	initialData: '<p>Section content.</p>'
+} );
+
+// Add an inline root.
+editor.addRoot( 'sectionTitle', {
+	modelElement: '$inlineRoot',
+	initialData: 'Section title'
+} );
+```
+
+The root type is fixed at creation time and cannot be changed afterward.
+
+## Styling the host element
+
+When you mount an inline root on a non-block HTML element such as a `<span>`, the browser may render the editable area with unexpected line breaks or sizing. This happens because block-filler mechanisms used by the editor can interact poorly with inline host elements.
+
+To avoid this, apply the following CSS to the editable element:
+
+```css
+.ck-editor__editable {
+	display: inline-block;
+	max-width: fit-content;
+}
+```
+
+This ensures the editing area does not collapse or stretch beyond its content. Mounting on a block element like a `<div>` does not require any extra CSS. See the {@link getting-started/setup/css Editor and content styles} guide for broader CSS customization options.
+
+<info-box>
+	When using a `<span>` as the host element, also set `display: inline-block` on the `<span>` itself, since block-level children are not valid inside an inline element.
+</info-box>

docs/updating/update-to-48.md

@@ -175,6 +175,8 @@ If your integration reads configuration values directly, update access paths as
 * `config.get( 'placeholder' )` -> `config.get( 'roots.main.placeholder' )`
 * `config.get( 'label' )` -> `config.get( 'roots.main.label' )`
 
+See the {@link getting-started/setup/root-types Root types} guide for a full overview of root configuration options.
+
 #### Dynamic root management
 
 The legacy signatures of `MultiRootEditor#addRoot()` and `MultiRootEditor#createEditable()` are deprecated and will be removed in a future release. They are replaced with new signatures that align with the way the editor root configuration is specified in `config.roots`.