CKEditor 5 customization

For Magnolia 6.3 installations, CKEditor 5 is the default rich text field. This page outlines how to build your editor, install it in Magnolia, and customize it for your needs.

A Magnolia instance includes one CKEditor 5 build, which may contain several editor types for pages requiring different editor configurations.

CKEditor 4 migration to CKEditor 5

Magnolia 6.2 uses CKEditor 4 in its rich text field. Magnolia 6.3 is released with CKEditor 5. While most field properties from Magnolia 6.2 are supported, CKEditor 4 and CKEditor 5 are very different in their core architecture. For this reason, Magnolia recommends previewing any content transferred from CKEditor 4 in Magnolia 6.2 and checking that the content is published as you want it.

In particular, you should check their compatibility tables for configuration and plugins to determine which content might be affected. Furthermore, follow their migration guidelines to ensure a smooth transition of any content.

If you use a custom build, Magnolia will ignore all the other configured properties in the rich text field.

Using a custom build

For more complex customizations (different plugins, editor types, and so on), you can replace the CKEditor 5 provided by Magnolia with your custom build by setting the MicroProfile property magnolia.ckeditor5.build to a light-module resource (for example, /custom-lm/webresources/ckeditor5.js) or an absolute URL.

To create a custom editor build for Magnolia:

Ensure you have Node.js or Node installed.
Clone the ckeditor5-plugins project from GitLab.
Install plugins via npm or manually add them to the CKEditor build.
- Use the npm install command, for example:
  npm install @ckeditor/ckeditor5-highlight@41.2.1 --save
- Or manually add the plugin to the dependencies section of the package file packages/ckeditor5-build/package.json:
  "dependencies": { //other dependencies ... "@ckeditor/ckeditor5-highlight": "^41.2.1" }
  For a complete list of CKEditor plugins, see CKEditor plugins.
Import the plugin into the CKEditor build and add it to the toolbar.
- Locate the ckeditor5.ts file under packages/ckeditor5-build/src.
- Add an import statement and reference it in BUILTIN_PLUGINS in the ckeditor5.ts file:
  ... import { Highlight } from '@ckeditor/ckeditor5-highlight'; const BUILTIN_PLUGINS = [ ... Highlight ]; ...
- Add the plugin to the toolbar:
  ... const DEFAULT_CONFIG : EditorConfig = { toolbar: [ ... '|', 'highlight' ], ...
  For more highlighting customization options, see CKEditor highlight options.
Export the editor by adding the export command at the end of the ckeditor5.ts file.

The exported editors can be retrieved by CKEDITOR5["ClassicEditor"] or CKEDITOR5["InlineEditor"]:
```
...
// Export the editor for CKEditor 5 to use in your project.
export default { ClassicEditor };
...
```
Rebuild the editor using the npm run build command.
Find the ckeditor5.js file under packages/ckeditor5-build/build.
Place the ckeditor5.js file into the webresources folder in a light module folder. For example, /module-lm/webresources/ckeditor5.js.
Configure the magnolia.ckeditor5.build property with the path to the ckeditor5.js file.
- You can do this via a JVM parameter:
  -Dmagnolia.ckeditor5.build=/module-lm/webresources/ckeditor5.js
- Or by defining it, for example magnolia.ckeditor5.build=/module-lm/webresources/ckeditor5.js, in the MicroProfile Config.
Restart your Magnolia instance.

JavaScript and CSS are bundled into a single file. Our custom build repository provides an example of how to achieve a custom build.

Including the custom build in Magnolia

Once your custom build is configured, use the editorType property to specify which editor from the ones included in the build you want to use.

form:
  properties:
    text:
      $type: richTextField
      editorType: ClassicEditor

Authoring your text

This page assumes you installed a Classic CKEditor. Your CKEditor toolbar should look similar to the one above the CKEditor demo page below.

Apps configuration

A customized CKEditor 5 build also contains two additional Magnolia plugins. They allow you to link to assets and pages in Magnolia.

Plugin Icon Description

Plugin	Icon	Description
Link to Magnolia page		Opens a chooser dialog where you can link to a page in the `website` workspace.
Link to asset		Opens a chooser dialog where you can link to an asset in the `dam` workspace.

Link to Magnolia page

Link to Magnolia page

Opens a chooser dialog where you can link to a page in the website workspace.

Link to asset

Link to DAM document

Opens a chooser dialog where you can link to an asset in the dam workspace.

Previewing the HTML

Preview your content to see how the plugins used by CKEditor 5 render it on the final webpage.