CKEditor module overview

Last updated on
15 September 2022

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:

  1. 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.
  2. 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 and data-caption attributes). By implementing that as data- 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

Tags

Help improve this page

Page status: No known problems

You can: