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.

  1. 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 CKEditorPlugin

    Review 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
    CKEditor plugins report page screenshot

    Review the report to indentify modules that provide CKEditor 4 plugins.

  2. 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.

  3. 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.

  4. 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+.

  5. Upgrade Text Formats

    CKEditor editor configuration is attached to individual text formats. Each text format will be upgraded individually.

    1. Navigate to the Text formats and editors admin page (/admin/config/content/formats).
    Image
    Text formats page screenshot
    1. Identify each format where the text editor is configured as "CKEditor".
    2. Navigate to the configuration page for each format.
    3. Change the value of the Text editor field to "CKEditor 5".
    Image
    Basic HTML page screenshot
    1. At this point, modules that provide an upgrade path will execute that upgrade against the editor configuration.
    Image
    Basic HTML page screenshot following upgrade
    1. Save the text format.
  6. 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).

  7. 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.