tessl/npm-ckeditor--ckeditor5-heading
Headings feature for CKEditor 5 that provides structured heading levels (H1-H6) and paragraph formatting with configurable UI components.
—
Pending
Quality
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
document-structure.mddocs/
Document Structure
Advanced document structuring capabilities that enable title and body sections for organized document creation. The Title plugin provides a specialized document structure with separate title and body areas.
Capabilities
Title Plugin
Plugin that splits the document into Title and Body sections, providing structured document organization with separate editing areas.
/**
* Plugin that splits document into Title and Body sections.
*/
class Title extends Plugin {
/** Plugin name identifier */
static readonly pluginName: 'Title';
/** Indicates this is an official CKEditor 5 plugin */
static readonly isOfficialPlugin: true;
/** Required plugins that are automatically loaded */
static readonly requires: ['Paragraph'];
/**
* Sets up title/body document structure and conversion.
* Initializes the document with title and body sections.
*/
init(): void;
/**
* Returns document title as plain text.
* @param options - Formatting options with default empty object
* @returns The title content as a plain text string
*/
getTitle(options: Record<string, unknown> = {}): string;
/**
* Returns document body content.
* @param options - Formatting options with default empty object
* @returns The body content as formatted text
*/
getBody(options: Record<string, unknown> = {}): string;
}Usage Examples:
import { Title } from '@ckeditor/ckeditor5-heading';
// Basic Title plugin usage
ClassicEditor.create(document.querySelector('#editor'), {
plugins: [Title, /* other plugins */],
title: {
placeholder: 'Enter document title here...'
}
});
// Access title functionality
const titlePlugin = editor.plugins.get('Title');
// Get title and body content
const title = titlePlugin.getTitle();
const body = titlePlugin.getBody();
console.log('Document title:', title);
console.log('Document body:', body);
// Set up event listeners for title changes
editor.model.document.on('change:data', () => {
const currentTitle = titlePlugin.getTitle();
console.log('Title updated:', currentTitle);
});Title Configuration
Configure the title section with custom placeholder text and behavior options.
/**
* Configuration interface for title feature.
*/
interface HeadingTitleConfig {
/** Custom placeholder text for title field */
placeholder?: string;
}Usage Examples:
// Configure title placeholder
const config = {
title: {
placeholder: 'Enter your document title...'
}
};
ClassicEditor.create(document.querySelector('#editor'), {
plugins: [Title],
title: config.title
});
// Multiple language support
const config = {
title: {
placeholder: t('Document Title Placeholder') // Localized placeholder
}
};Document Structure Layout
The Title plugin creates a structured document with two distinct sections:
Title Section:
- Single-line title area at the top of the document
- Typically rendered as an H1 element
- Focused editing experience for document titles
- Custom placeholder text support
Body Section:
- Multi-paragraph content area below the title
- Supports all standard CKEditor 5 features
- Independent formatting from the title
- Full rich text editing capabilities
// Document structure example:
// ┌─────────────────────────────────┐
// │ Document Title Here... │ ← Title section
// ├─────────────────────────────────┤
// │ Body content starts here. │ ← Body section
// │ │
// │ Multiple paragraphs and other │
// │ content can be added here. │
// │ │
// │ [Additional content...] │
// └─────────────────────────────────┘Content Extraction Methods
The Title plugin provides methods to extract content from both sections:
getTitle() Method:
- Returns the title content as plain text
- Strips all formatting and returns clean text
- Useful for document metadata, file names, or search indexing
getBody() Method:
- Returns the body content in the specified format
- Preserves formatting by default
- Can be configured with options for different output formats
// Content extraction examples:
const titlePlugin = editor.plugins.get('Title');
// Get plain text title
const title = titlePlugin.getTitle();
// Returns: "My Document Title"
// Get body content with formatting
const body = titlePlugin.getBody();
// Returns formatted content with HTML/markup
// Use extracted content
document.title = title; // Set browser tab title
localStorage.setItem('documentTitle', title);
localStorage.setItem('documentBody', body);Schema and Model Integration
The Title plugin integrates with CKEditor 5's schema system:
Title Model Element:
- Registered as a special block element
- Restricted to text content only
- Cannot contain other block elements
- Positioned at the document root
Body Model Element:
- Standard document root container
- Supports all configured block elements
- Allows paragraphs, headings, lists, etc.
- Independent formatting from title
// Internal model structure:
// <title>Document Title</title>
// <body>
// <paragraph>First body paragraph.</paragraph>
// <heading1>Body heading</heading1>
// <paragraph>More content...</paragraph>
// </body>Navigation and Editing Behavior
The Title plugin provides specialized editing behavior:
Title Focus:
- Tab/Enter from title moves to body
- Backspace at start of body moves to title
- Title field automatically expands with content
Body Focus:
- Standard CKEditor 5 editing behavior
- All plugins and features available
- Independent formatting from title
// Keyboard navigation:
// - Tab in title → moves to body
// - Shift+Tab in body → moves to title
// - Enter in title → creates new paragraph in body
// - Up arrow at start of body → moves to titleIntegration with Other Features
The Title plugin works alongside other CKEditor 5 features:
With Heading Plugin:
- Title section separate from heading functionality
- Body can contain H2-H6 headings
- Title typically rendered as H1 in output
With Export/Save Features:
- Title and body can be extracted separately
- Useful for document metadata systems
- Supports different output formats
// Integration example:
ClassicEditor.create(document.querySelector('#editor'), {
plugins: [Title, Heading, /* other plugins */],
toolbar: ['heading', 'bold', 'italic'], // Available in body
title: {
placeholder: 'Document Title'
},
heading: {
options: [
{ model: 'paragraph', title: 'Paragraph', class: 'ck-heading_paragraph' },
// Note: No heading1 since title serves as H1
{ model: 'heading2', view: 'h2', title: 'Heading 2', class: 'ck-heading_heading2' },
{ model: 'heading3', view: 'h3', title: 'Heading 3', class: 'ck-heading_heading3' }
]
}
});Install with Tessl CLI
npx tessl i tessl/npm-ckeditor--ckeditor5-heading