Problem/Motivation
Drupal 8 is running on CKEditor 4.x. CKEditor 5.x has gone stable and looks like it has enhancements to help improve the authoring experience.
CKEditor 5 also no longer relies on inline JavaScript, which requires a more permissive Content Security Policy due to its use in CKEditor 4 (#2789139: [upstream] CSP requires 'unsafe-inline' because of CKEditor 4).
Proposed resolution
General requirement: the high-level existing features documented at https://www.drupal.org/docs/8/core/modules/ckeditor/overview continue to exist. If there are strong reasons to not have those features anymore, it needs sign-off from Drupal product managers. Those are: structured content, clean markup, integrates with filter system, paste from Word/Google Docs, drag-and-drop text editor configuration UI, strong safety guarantees, contrib extensibility.
Remaining tasks
The plan:
- ✅ Phase 1: Basic PoC
- ✅ Add
core/modules/ckeditor5
.
- ✅ Create an
@Editor
PHP plugin with the ID ckeditor5
.
- ✅ Create a
Drupal.editors
JS plugin with the ID ckeditor5
.
- ✅ Getting CKE5 (CKEditor 5) to load at all on the
/node/add/article
form.
- Phase 2: Critical technical aspects. (These should be tackled first since they come with the highest amount of risk and architectural work.)
- Ensure
filter_html
's HTML restrictions are respected inside CKE5 just like in CKE4's Advanced Content Filter (which CKE4 added specifically for Drupal). Why? [Because it] 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.
(I have no concerns about this thanks to CKE5's model).
- Related: ensure that arbitrary HTML is not lost — see https://github.com/ckeditor/ckeditor5/issues/592 and comments #49–#51.
- CKE4 uses an
<iframe>
-based text editor in forms. CKE5 no longer has an <iframe>
mode. This means that the admin theme's CSS automatically applies. This also means that there's no obvious way to port the ckeditor_stylesheets
feature that enabled the default (front end) theme to make CKEditor instances in the back end to generate previews that approximately or even precisely match the front end (the default theme). (See CKEditor iframe css
at https://www.drupal.org/docs/8/api/ckeditor-api/overview.)
- Phase 3: Critical integration aspects
- Enable a Drupal + CKE5 ecosystem, just like we have today for Drupal + CKE4: https://www.drupal.org/documentation/modules/ckeditor/contrib. This means we need Drupal modules to be able to add additional CKEditor plugins to be loaded and configured. See
CKEditor Plugin plugins
at https://www.drupal.org/docs/8/api/ckeditor-api/overview for the current five PHP interfaces that @CKEditorPlugin
plugins are able to implement. Also relevant information in #28 (by CKEditor 5 Lead Developer @Reinmar) and #32 (big meeting with Drupal maintainers & CKEditor maintainers).
- A CKE5 configuration UI like
/admin/config/content/formats/manage/basic_html
. Noteworthy: the current UI is even fully keyboard accessible. This is evidently blocked on the previous bullet. Also relevant information in #28 (by CKEditor 5 Lead Developer @Reinmar) and #32 (big meeting with Drupal maintainers & CKEditor maintainers). - Ensure there is a great authoring experience that still results in structured content. For example Drupal stores
<img src=… alt=… data-align=… data-caption=…>
, but CKE4 renders something very different than just an <img>
, thanks to CKEditor Widgets. In the talks that @Reinmar linked in his comments #50 and #51 it's clear that the structured content is not a problem (just a matter of extending the CKE5 model) nor is the different presentation for the content author (just a matter of extending the CKE5 view).
- Phase 4: Polish
- Evaluate all of Drupal core's CKE4 plugins:
DrupalLink
, DrupalImage
and DrupalImageCaption
. For all of these, we should ask ourselves whether we truly need Drupal to maintain custom integration code for them. Do some git
and issue queue archeology to assess the rationale for each of them. In short, for DrupalLink
it was that CKE4's link
plugin was overly complex, offering the end user 37 choices whereas just the one would suffice. For DrupalImage
: same. For DrupalImageCaption
: CKE4 at the time would always store the <figure>…<figcaption>This is the caption.</figcaption></caption>
markup, which was unacceptable to Drupal since it violates our structured content principles. CKE5 evidently is doing much better on that front, so perhaps we can now drop that altogether?
- Evaluate all Drupal's choice to not use CKE4's dialogs but our own server-side rendered ones to allow Drupal modules to
hook_form_alter()
. (This is true for the plugins mentioned in the previous bullet.) Perhaps in Drupal 9 we can choose to not offer Drupal-PHP-alterable forms and require developers to customize their CKE5 build?
- Ensure Quick Edit integration works (the PoC already contains
InlineEditor
) - Evaluate all other existing integration tweaks and assess whether we want to continue to have them. For example: CKE4 felt very constrained and annoying out of the box, so we added
autogrow
support and tweaked that further — CKE 5 already does this out of the box! 🥳
- Ensure CKE4 and CKE5 can co-exist — currently having both instantiated on the same page results in errors (because for example
Basic HTML
uses CKE5 and Full HTML
uses CKE4 since only CKE4 allows entering arbitrary HTML)
- Ensure CKE5 continues to work well in the Off-Canvas Dialogs; for CKE4 this required a complex CSS reset.
- #1890502: WYSIWYG: Add CKEditor module to core landed on February 8, 2013. A few days shy of 6.5 years ago. #2469713: Step 2: Create a JavaScriptTestBase using PhantomJs Driver/Binary landed on March 15, 2016. About 3 years and 3 months ago. This is why D8 + CKE4 barely has JS test coverage. Let's do better for D9 + CKE5.
- Phase 5: Update Path
While doing this work to bring CKE5 to D9, we should do two things on every step along the way:
git
and drupal.org issue queue archeology to understand why certain choices were made in the D8 + CKE4 integration. When D9 + CKE5 wants to deviate from those choices, be explicit about this and have comments explaining why choices should be different now. This will help D11 + CKE7 😜- Work with the CKE5 team! They're an awesome, responsive bunch that will try their best to help us use their work 🥳 #32 is a good example of this :)
User interface changes
TBD. Current status:
![]()
API changes
A migration guide has been provided from migrating from 4.x to 5.x, covering plugins, skins, and APIs:
Data model changes
None.