CKEditor 4 customization

You can customize CKEditor 4 using a JavaScript configuration file. Magnolia’s rich text field and light rich text field use CKEditor 4 as their editor. There are two default configurations: config-magnolia.js and config-default.js.

If you use a custom configuration file, Magnolia ignores all the other configured properties.

The default configuration files can be found in magnolia-ui-framework-jcr/src/main/resources/mgnl-resources/ckeditor/:

You can locate the custom configuration file in the resources workspace, file system, or classpath (for example, /.resources/ckeditor/config-magnolia.js).

For more information about creating different CKEditor configurations to optimize the authoring experience, see Customizing the RichText field using CKEditor.

Magnolia configuration file

The Magnolia configuration file is a subset of the default CKEditor configuration. It includes external Magnolia functions described in the table below.

Default Magnolia toolbar

Rich text field toolbar

Function Icon Description

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.



Expands the rich text field.

CKEditor configuration file

The CKEditor configuration includes the entire toolbar, as shown in the screenshot below.

Rich text field - CKEditor default config

CKEditor provides a tabbed dialog for inserting links (such as anchor tags) into rich text.

CKEditor tabbed link dialog

The fields of this tabbed dialog map to the following element attributes:

Field ID Attribute





Language direction


Language code


Access key


Tab index


Advisory title


Advisory content type


Stylesheet classes


The style field expects inline style values to consist of one or more tuples with the format "name : value", separated by semi-colons.

Linked resource charset




Force download


Renders an empty attribute with no value.
Because a rich text editor adds HTML to your content, the HTML will be indexed by search engines along with the content.

Customizing via a configuration file

Both default configuration files contain a CKEDITOR.config section in which default settings are stored. For example, whether Latin characters are converted to HTML entities can be defined using the entities_latin setting.

config.entities_latin = false;

Alternatively, you can customize how basic text styles appear in the HTML output. For example, you can implement the Bold feature in different ways: <strong>, <b>, <span style="font-weight: bold;">, or <span class="Bold">.

Use case example: Latin characters

Instructions to add the entities_latin setting to the default Magnolia configuration file and illustrations are given below.

  1. Add the config.entities_latin = false; property to the /ckeditor/config-magnolia.js custom file.

    See how to do it…​

    Editing the config-magnolia.js file

  2. Update the textImage.yaml mtk2 component dialog file to reference the updated configuration file (for example configJsFile: /.resources/ckeditor/config-magnolia.js).

    See how to do it…​

    Editing the textImage.yaml file

  3. Create a page and add a new Text and image component, including Latin characters (boรฎte ร  lettres, for instance). Check that the characters are displayed properly.

  4. Go to the JCR app and find the page and text field you created. Check that the characters in the value field are correctly displayed.

    Inspecting Latin characters in the JCR

Content appearance inside the editor

By customizing a CKEditor 4 stylesheet, you can achieve consistent styling for content both inside and outside the editor.

It is done by specifying custom styles for edited content using the config.contentsCss setting. For more information, see Classic Editor with Custom Styles.

Use case example: Custom CKEditor CSS

The default Magnolia configuration includes a basic presentation configuration for black text on a white background with minimal styling. However, it may be more beneficial for editors to see a preview closer to how their text is rendered: using the same font, for example, or styled bullet points.

You can’t achieve this level of customization using just light modules. You must use a custom Java component instead. To handle loading from different application contexts, place the file inside a VAADIN directory in the Maven module’s resources directory.

๐Ÿ“ src

     ๐Ÿ“ main

         ๐Ÿ“ resources

             ๐Ÿ“ VAADIN

From this location, you can refer to the VAADIN directory inside a JavaScript configuration. Subdirectories can be created inside the VAADIN directory. For example, a custom CSS file is inside a CSS directory.

config.contentsCss setting
config.contentsCss = CKEDITOR.vaadinDirUrl + <THE_CSS_FILE>;

You can deploy the CSS file via the resource loading framework. The config.js file, which contains the config.contentsCss setting, is then accessible via /.resources/<MY-MODULE>/resources/config.js

๐Ÿ“ src

     ๐Ÿ“ main

         ๐Ÿ“ resources

             ๐Ÿ“ <MY_MODULE>

                 ๐Ÿ“ webresources

                     โฌฉ config.js

Adding drop-down styles to the toolbar

You can also introduce drop-downs in the CKEditor toolbar by adding to one of the default configurations. An example of a styles drop-down is given below. For more information, go to CKEditor Defining Styles or CKEditor Applying Block-Level Text Formats.

Adding a stylesSet within the CKEDITOR.editorConfig
config.stylesSet = [
  // Block-level styles
  { name: 'Blue Title', element: 'h2', styles: { 'color': 'Blue' } },
  { name: 'Red Title' , element: 'h3', styles: { 'color': 'Red' } },

  // Inline styles
  { name: 'CSS Style', element: 'span', attributes: { 'class': 'my_style' } },
  { name: 'Marker: Yellow', element: 'span', styles: { 'background-color': 'Yellow' } }

CKEditor style drop-down

Installing plugins

You can add plugins to extend the Rich text fieldโ€™s functionality. Some plugins are already added in the default configurations. For example, see the Special character’s use case in this section.

For others, such as the word count plugin, you need to download the respective plugin from CKEditor and manually add it to a Java moduleโ€™s VAADIN folder under src/main/resources/VAADIN/js.

Using the CKEditor Maximize plugin may lead to display issues with the external Link to Magnolia page and Link to DAM document Magnolia functions. It is highly recommended that you use the external Expand Magnolia function instead.

Use case example: Special characters

This section shows an example configuration customizing the special characters in CKEditor 4.

When a Rich text field is added to a dialog, it uses a configuration customized by Magnolia to include some specific plugins for linking to content and disabling some others.

The Special Characters plugin is enabled by default and provides an on-screen selection of non-standard characters an editor can add to a page.

See the CKEditor4 source for the full collection of default characters.

CKEditor configuration

As per the CKEditor4 documentation, the array of characters to offer authors is provided as config.specialChars.

Additionally, you can provide a label for a character by providing an array of two elements: the character and the label. Therefore, you can extend the default set and add a character using:

config.specialChars = config.specialChars.concat(['\&#9660;']);

Or add a character with a label using:

config.specialChars = config.specialChars.concat([ ['\&nbsp;','NB Space'] ]);

Those examples append a character to the end of the menu presented to editors. Bringing them to the start may make sense if you know frequently used characters. This is achieved by reversing the concat function:

config.specialChars = ['\&#9660;'].concat(config.specialChars);

Or you may replace the large default selection of characters and only provide those you believe editors need by replacing the entire array, as shown below.

config.specialChars = [
    ['&nbsp;','NB Space'],
    ['&#9660;','Black Down-Pointing Triangle']];

CKEditor integration and definition

The modified config file can be deployed via the webresources folder of a light module.

๐Ÿ“ my-light-module

     ๐Ÿ“ config

         ๐Ÿ“ webresources

             โฌฉ config.js

This file is then accessible via the path /.resources/my-light-module/webresources/config.js. The final step is to modify the Rich text field definition and see configuration changes in the respective component dialog.

  $type: richTextField
  label: Customized CKEditor
  configJsFile: /.resources/field-examples/webresources/ckeditor/config-magnolia-extended.js

DX Core



This widget lets you know where you are on the docs site.

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules
6.3 beta

Magnolia 6.3 beta

Magnolia 6.3 is in beta. We are updating docs based on development and feedback. Consider the 6.3 docs currently in a state of progress and not final.

We are working on some 6.3-beta known issues during this phase.