Upgrading to CKEditor 5
- Last updated
- 1 minute read
Goal
Prepare for and upgrade to CKEditor 5
Overview
In Drupal 8, the community decided to standardize on the CKEditor rich text editor, specifically CKEditor 4. Just as other dependencies reach of end of life, so will CKEditor 4, on 31 December 2023 to be exact. In Drupal 9.5, CKEditor 5 was added to core, including an upgrade process. While CKEditor 4 continues to be part of Drupal 9, it was mirrored* to a contrib CKEditor project and was removed in Drupal 10.
For new Drupal installations, CKEditor 5 is the default editor. When existing Drupal sites are updated to Drupal 9.5, no changes are made automatically. This tutorial will provides steps to upgrade to CKEditor 5.
*If a given codebase has any modules that declare a dependency on either drupal/ckeditor or ckeditor/ckeditor, then Composer will install the contrib version of CKEditor 4.
-
Find Modules that Provide CKEditor 4 Plugins
The first step in CKEditor 5 preparedness is determining which modules provide CKEditor 4 plugins. While some modules make it obvious by using "CKEditor" in their title, others do not. For example, both the Linkit and Inline Responsive Images modules provide CKEditor 4 plugins.
Option 1: Grep
Use grep to search the codebase for "CKEditorPlugin":
cd docroot/modules grep -R CKEditorPluginReview the grep results to identify modules that provide CKEditor 4 plugins.
Option 2: CKEditor Plugin Report
Install the CKEditor Plugin Report module and navigate to the CKEditor plugins report page (/admin/reports/ckeditor-plugins):
Image
Review the report to indentify modules that provide CKEditor 4 plugins.
-
Determine CKEditor 5 Readiness of Contrib Modules
Next, determine the CKEditor 5 readiness of each conrib module identified in the previous step.
The Upgrade coordination for modules providing CKEditor 4 plugins page on Drupal.org provides an extensive list of modules that provide CKEditor plugins, including their CKEditor 5 readiness and a link to the relevant issue where CKEditor 5 readiness is being worked on. Be sure to review the individual issues as progress may have been made since the list was last updated. In the event a module is not listed, search the issue queue for that module.
-
Upgrade Custom Modules
In the event the codebase contains custom code, which provides a CKEditor 4 plugin, that module will need updated for CKEditor 5 compatibility. See the Upgrading modules extending CKEditor 4 to support CKEditor 5 page on Drupal.org for more information.
-
Install CKEditor 5
Once all modules, contrib and custom, are updated to CKEditor 5-compatible versions, it will be possible to upgrade text formats to CKEditor 5.
At this point, install the CKEditor 5 module, which is provided in Drupal 9.5+.
-
Upgrade Text Formats
CKEditor editor configuration is attached to individual text formats. Each text format will be upgraded individually.
- Navigate to the Text formats and editors admin page (/admin/config/content/formats).
Image
- Identify each format where the text editor is configured as "CKEditor".
- Navigate to the configuration page for each format.
- Change the value of the Text editor field to "CKEditor 5".
Image
- At this point, modules that provide an upgrade path will execute that upgrade against the editor configuration.
Image
- Save the text format.
-
Test
As with any upgrade, testing is an important part of the upgrade process. Confirm that all features and functionality behave as expected before deploying to your production site(s).
-
Uninstall CKEditor 4 Module
Once all text formats have been upgraded and testing is complete, uninstall the CKEditor 4 module.
Additional Resources
Check out the official CKEditor 5 development documentation on Drupal.org.
Join Drupal Slack, specifically for the #ckeditor5 channel.
