By lauriii on
Change record status: 
Published (View all published change records)
Project: 
Drupal core
Introduced in branch: 
9.3.x
Introduced in version: 
9.3.9
Issue links: 
https://www.drupal.org/node/3194084
Description: 

Custom styles can be loaded from the site's default theme on a page where CKEditor 5 is loaded using a new ckeditor5-stylesheets key in a theme's .info file.

This behaves differently than the ckeditor_stylesheets key used for CKEditor 4. Unlike CKEditor 4, CKEditor 5 is not provided via <iframe>, so a stylesheet added via ckeditor5-stylesheets will be applied to the entire page. Depending on the contents of your stylesheet, it may be necessary to provide an additional ckeditor5-specific stylesheet. Use the table below to determine if this is necessary, and what customizations would be needed were that the case.

Determining the steps needed to load a default theme stylesheet in CKEditor 5

Situation Solution
If your existing ckeditor_stylesheets: files are only targeting selectors that do not appear in your admin theme. This means

- there aren't generic selectors such as h1-h6, ul, table, etc.
- Every selector is accompanied by a theme specific id or class that does not appear in the admin theme.
- There aren't selectors on elements that appear as parents of the CKEditor field, such as <body> or <html>

 In this case you can probably just add the same stylesheet to ckeditor5-stylesheets with no additional modifications needed. 
ckeditor_stylesheets:
  - css/a-stylesheet.css
ckeditor5-stylesheets:
  - css/a-stylesheet.css

Please note: The underscore has changed to a hyphen.

HOWEVER: CKEditor 5's default styling is a big improvment from CKEditor 4's. Be sure your stylesheet isn't overriding something you may prefer!

There are selectors in your CSS that potentially appear on the page outside of the field using CKEditor 5. Create a new stylesheet specifically for CKEditor 5. Selectors likely to appear outside of the editor should be prefixed with .ck-content

Example:
CKEditor 4
if you were adding base.css to ckeditor_stylesheets:

ckeditor_stylesheets:
  - css/base.css

And the contents included:

# css/base.css
h2 {
  color: blue;
}

CKEditor 5
You'll want to create a copy of base.css customized for use with CKEditor 5

ckeditor5-stylesheets:
  - css/base-ckeditor5.css

# css/base-ckeditor5.css
/* Prefix the h2 with .ck-content to keep the style in the editor, and avoid polluting the page with unwanted h2 styles */
.ck-content h2 {
  color: blue;
}
At least some of the CKEditor 5 default styles are preferable to what the added stylesheet provides. (There are situations where not fully reproducing the front-end theme results in a better editing experience, such as tables and lists.) Add a ckeditor-specific stylesheet (as shown in the above table cell), and remove the styles conflicting with the desired CKEditor 5 defaults
Your text format reports that you have themes using the ckeditor_stylesheets setting without an equivalent ckeditor5-stylesheets setting, but you have no need to add stylesheets for CKEditor 5 In your top-level theme(s), set ckeditor5-stylesheets: false to remove the warning without having to add any stylesheets.
Impacts: 
Themers

Comments

redseujac’s picture

redseujac
he/him/his
Primary language Dutch
Location Ieper, BE 🇧🇪
commented

I wanted to test the core experimental CKEditor 5 in my Drupal 9.4.1. It does not work and leads to "The website encountered an unexpected error. Please try again later." Notice I use core’s “Seven” theme as an administration theme, and I checked the box to use the administration theme for my node forms.

I installed and enabled core experimental CKEditor 5 and selected it as full html editor. As expected text format reports that I have themes (Classy and Seven) using the ckeditor_stylesheets setting without an equivalent ckeditor5-stylesheets setting.

So I went to core/themes/classy and edited the Classy.info.yml. After the key ckeditor_stylesheets and its content, I added ckeditor5-stylesheets: false. I did the same for the theme Seven.

I cleared all caches. Nothing to do. It doesn't work and when I want to edit a node or create a new one, I get "The website encountered an unexpected error".

What am I doing wrong?

Edit: I found the culprit. It was due to the modules "Insert" and "Colorbox Insert". I uninstalled those modules and it's working now even without ckeditor5-stylesheets: false.

Conclusion: ckeditor 5 is not compatible with the modules Insert and Colorbox insert.

dunx’s picture

dunx commented

Might I suggest you raise two specific issues @redseujac as your info may get lost here.

jwilson3’s picture

jwilson3
Primary language English
Location Ecuador
commented

I've written a tutorial for how to add ckeditor5-stylesheets for a Radix-based subtheme here leveraging Laravel Mix, SASS, and PostCSS to namespace your frontend theme styles without needing to rewrite all your CSS for CKE5 compatibility.

https://www.drupal.org/project/radix/issues/3386641#comment-15226379

This could evolve into a more generic docs page eventually. Feedback, generalizations and improvements welcome!

hudri’s picture

hudri
Primary language German
Location Austria
commented

Note that you must add your ckeditor5-stylesheets in your default frontend theme info file (or a parent theme of the default theme). It does not work if you add it to your admin theme, or if you are using dynamic themes from a theme switcher module.

robbdavis’s picture

robbdavis commented

Seems obvious in retrospect but I lost an hour or more to not noticing that the underscore has changed to a hyphen and hunting for why my style sheet wasn't loading in ckedtior5.

alex.skrypnyk’s picture

alex.skrypnyk
he/him
Primary language English
Location Melbourne
commented

The code in _ckeditor5_theme_css() will try to load the parent's theme definition of ckeditor5-stylesheets if the child does not provide it. The path(s) to files, in such case, will be resolved agains the parent's theme path.

Founder, Software Engineer | www.drevops.com

druplr’s picture

druplr commented

Hi alex.skrypnyk. It doesn't seem to be the case. Please see this issue I just created: Allow overriding/disabling base theme's ckeditor5-stylesheets value. Have you seen this somewhere in the documentation? Thanks.