CKEditor module overview
This documentation is for the CKEditor module that was deprecated from core in Drupal 9.5.0, removed from core in Drupal 10.0.0-beta1, and moved to a contributed project. As of Drupal 9.5.0, the core uses the CKEditor 5 module.
It is inspired by the Drupal 7 Wysiwyg module and is the spiritual successor to the Drupal 7 CKEditor module. Think of it as the best of both, and then much better still!
Features
The CKEditor module builds on Drupal 8's Text Editor module to provide a deeply integrated CKEditor text editor out of the box. Unlike the contributed module in Drupal 7, the CKEditor module in Drupal 8 core:
- still ensures structured content and clean markup (and works with rather than around the filter system)
- significantly improved support for pasting from Microsoft Word, Google Docs, etc.
- has an easy-to-use drag-and-drop-based UI to configure CKEditor's toolbar (and automatically updates your filter settings, so you don't have to worry about it: just dragging and dropping the buttons you want is enough 99% of the time) — also: no more need to modify JavaScript files to change certain things
- has strong safety guarantees that protect content editors
Noteworthy technical background information
In order to achieve this, Drupal contributors have closely collaborated with the CKEditor team (and continue to do so: it is maintained by both members of the Drupal community and the CKEditor team!). The CKEditor team has developed significant new features, especially for Drupal 8. Here are the two most important ones:
- ACF, or Advanced Content Filter (in CKEditor 4.1), that allows Drupal to guarantee CKEditor generates clean markup, and only markup that is allowed by Drupal's filters, which means CKEditor's markup preview matches the output exactly.
- The CKEditor Widget system (in CKEditor 4.3), allows Drupal to provide a great UX for filters that apply transformations. For example, Drupal 8 allows you to align and caption images via filters (using the
data-align
anddata-caption
attributes). By implementing that asdata-
attributes that filters can process on output, we continue to store semantic, structured content that can easily be transformed in different ways on output (and even uses a themable template!). To not burden content authors with that, Drupal 8 uses the CKEditor Widget API to provide an intuitive way to add a caption to an image.
Using CKEditor Widgets for a better, tailored authoring experience
The two aforementioned features are essential to using a text editor with Drupal for a better UX, while still supporting the same robust structured content/data modeling. Drupal 8 sites can implement custom filters (like before) to fulfill their content authoring needs, but now can provide a much better experience by writing a CKEditor plugin that hugely improves the authoring experience for those site-specific needs, by using both the Widget and ACF APIs.
Think callouts, footnotes, e-commerce product references, code snippets, mathematical formulas, and more.
Custom configuration
To quickly start adding custom configuration to CKEditor in Drupal 8:
1. Install the CKEditor Custom Config module
2. Create an empty file called 'ckeditor.config.custom.js' (or whatever) in your theme (themes/custom/<my_theme>)
3. Edit your text format (/admin/config/content/formats/<my_format>), and add this snippet under 'CKEditor Custom Configuration' (from #34):
customConfig = "/path/to/my/theme/ckeditor.config.custom.js"
5. Inside ckeditor.config.custom.js
, add:
// Custom configuration for CKEditor
CKEDITOR.editorConfig = function( config ) {
// Add configuration options here
// https://ckeditor.com/docs/ckeditor4/latest/api/CKEDITOR_config.html)
// Examples:
// Load the German interface.
config.language = 'de';
// Prevent removing empty <i> tags
config.protectedSource.push(/<i[^>]*><\/i>/g);
etc...
};
6. Rebuild the cache. Changes won't be picked up unless you do!
Read more about applying a custom configuration in the official CKEditor documentation.
Issue queue
http://drupal.org/project/issues/drupal?component=ckeditor.module
See also
- Filter module: text formats that filter user input
- Text Editor module: associating assistive editors with text formats
- CKEditor API
- Drupal 8: best authoring experience for structured content?
- CKEditor in Drupal 8: site builders & developers Q&A's
- List of contributed modules and plugins for Drupal 8 CKEditor
Help improve this page
You can:
- Log in, click Edit, and edit this page
- Log in, click Discuss, update the Page status value, and suggest an improvement
- Log in and create a Documentation issue with your suggestion