Try Drupal 9's CKEditor 5 upgrade path!

Together with zrpnr, gabesullice, lauriii, bnjmnm, yashrode and hooromoo in Acquia’s Drupal Acceleration Team, I’ve been working on getting Drupal on CKEditor 5, because CKEditor 4 is reaching the end of its long and productive life.

zrpnr got it started in January 2021. We’ve been meeting with Reinmar 1 from the CKEditor 5 team to ensure a smooth automatic upgrade path from CKEditor 4: all functionality should be even better! Less than 10 months later, on November 11, 2021, CKEditor 5 was committed to Drupal 9.3!

But … it’s not yet stable. It’s an experimental module. We have a roadmap to get CKEditor 5 stable. In the next few months, we need the CKEditor 5 team to fix bugs and add missing features (most notably the beloved StylesCombo 2) upstream bugfixes and features to happen, and we need to get the Drupal side of things in order. We’re working hard to make that happen!

Automatic upgrade path!

We need ~434,000 Drupal 8 and 9 sites to make a fully automated upgrade from CKEditor 4 to 5. But they have vastly different architectures 3, which has significant consequences for that upgrade path. Virtually every detail is different! So:

  1. How do we ensure that the toolbar people get to use looks as similar as possible?
  2. How do we ensure that all HTML that was already created in CKEditor 4 continues to work fine in CKEditor 5?
  3. How do we ensure the same HTML restrictions are enforced by CKEditor 5?
  4. How do we ensure that HTML tags/attributes/attribute values allowed by a Drupal text format match those of the corresponding CKEditor 5 text editor exactly?
  5. How do we communicate changes in the toolbar to the site builder?
  6. Does the resulting text editor experience match your expectations?

How you can help?

We believe we’ve answered the first 5 questions in that list. The 6th … we really need to hear from as many of you as possible! So … we’d very much appreciate you giving it a try. In fact, the weirder/more complex your text format, the more we would love you to give it a try and report back!

So if in this upcoming Global Contribution Weekend, you could:

Your browser does not support playing videos. You can download it instead.

What switching from CKEditor 4 to CKEditor 5 looks like.

Or, in a bit more detail (the video shows you what to expect — but doesn’t show the terminal bits in steps 6 & 8):

  1. Install the CKEditor 5 module. Make sure you’re on Drupal 9.3 — because CKEditor 5 is experimental every commit not only goes to 9.4 (and 10.0) but also 9.3!
  2. Go to /admin/config/content/formats
  3. Find the most complex text format on your site that indicates CKEditor is its text editor
  4. Click its Configure operation
  5. Copy the machine name (for example: basic_html)
  6. In a terminal, do

drush cget filter.format.MACHINE_NAME > MACHINE_NAME-format-before.ymldrush cget editor.editor.MACHINE_NAME > MACHINE_NAME-editor-before.yml

  1. In the browser, find the Text editor dropdown, choose CKEditor 5 instead of CKEditor. Ignore what happens for a moment, go to the next step.
  2. In a terminal, do

drush cget filter.format.MACHINE_NAME > MACHINE_NAME-format-after.ymldrush cget editor.editor.MACHINE_NAME > MACHINE_NAME-editor-after.yml

  1. In the browser, look at what actually happened. Write down your observations, concerns, fears, celebrations. We want to hear about it!

When updating to Drupal 10, the manual above will happen automatically for text formats whose text editor was still CKEditor 4. In Drupal 9.3 and 9.4 it is a manual action that you can choose to opt in to — and we’re just asking you to do that action, and provide before + after states plus your own observations.

Practical

Upload the YAML files you created and post your observations at https://www.drupal.org/project/drupal/issues/3260695!

I’ll be around in the #ckeditor5 Drupal Slack channel and on Zoom to answer questions:

  • on Friday Jan 28, 15:00–17:00 UTC 4
  • on Saturday Jan 29, 16:00–17:00 UTC
  • on Sunday Jan 30, 16:00–17:00 UTC

Hope to see you there!

  1. Fun fact: Piotr and I previously collaborated roughly a decade ago to bring CKEditor 4 to Drupal 8, which got committed on February 8, 2013! ↩︎

  2. Add your thumbs up to that CKEditor 5 GitHub issue to show how many Drupal users love this feature! ↩︎

  3. In a nutshell: CKEditor 4 leverages the browser as much as possible. Consequence: any tiny difference in behavior across browsers in low-level APIs has a huge negative impact. CKEditor 5 therefore avoids using the browser for many low-level operations, and re-implements many things. This way, it can guarantee consistency and reliability. But consequently, not all HTML is natively supported anymore! ↩︎

  4. Or for the pilots among you: between 2022-01-28T15:00:00Z and 2022-01-28T17:00:00Z — this one is for you Gabe :D ↩︎

Original Article: