Configuration Reference

editor.config

editor.config

Configuration options For a list of all options see https://ckeditor.com/docs/ckeditor5/latest/api/module_core_editor_editorconfig-EditorConfig.html

Note

Some configuration options from the official CKEditor 5 documentation do not apply to TYPO3, since they are related to specific plugins (for example: CKBox, CloudServices) which are not bundled in TYPO3's CKEditor build.

editor.config.language

defines the editor’s UI language, and is dynamically calculated (if not set otherwise) by the backend users’ preference.

editor.config.contentsLanguage

defines the language of the data, which is fetched from the sys_language information, but can be overridden by this option as well. For referencing files, TYPO3's internal "EXT:" syntax can be used, for using language labels, TYPO3's "LLL:" language functionality can be used.

editor.config.contentsCss

defines the location of one or multiple CSS file(s) of the editor, containing the style definitions that will be applied to the backend editor RTE element.

Example with single file:

editor.config.contentsCss:
  - "EXT:rte_ckeditor/Resources/Public/Css/contents.css"

Copied!

This is the default, as defined in EXT:rte_ckeditor/Configuration/RTE/Editor/Base.yaml (GitHub).

Example with multiple files:

editor.config.contentsCss:
  - "EXT:rte_ckeditor/Resources/Public/Css/contents.css"
  - "EXT:my_sitepackage/Resources/Public/Css/contents.css?v=2"

Copied!

Since the CKEditor element is rendered within the page content of the TYPO3 backend (and not in an iframe or web-component), all CSS declarations in that file must refer to an actual element hierarchy ending like #data_tt_content__2687__bodytext_ckeditor5 .ck-content. To achieve this, TYPO3 automatically parses the contents of the CSS file with a process called "auto-prefixing" (via JavaScript, client-side) and converts all references to that "virtual" root hierarchy.

A CSS declaration like :root { background-color: green } gets turned into #data_tt_content__2687__bodytext_ckeditor5 .ck-content { background-color: green; }.

You can use a :root { ... } declaration, for example to reset relative/absolute sizes to ensure the CKEditor area being compatible to your usual frontend CSS. Also using body {...} is viable.

Note

Referenced CSS stylesheets need to be downloadable via fetch() in order for the JavaScript-based prefixing to work.

Note

Also note that the generated CSS file is cached by your browser. If you change the contents of your CSS file, be sure to either reload the browser cache, or use a directive like editor.config.contentsCss: "EXT:my_sitepackage/Resources/Public/Css/contents.css?v=2" where you change the ?v= URI string after any file modification to enforce requesting an updated version of the file.

editor.config.heading

Defines headings available in the heading dropdown.

Example:

heading:
  options:
    - { model: 'heading2', view: 'h2', title: 'Heading 2' }
    - { model: 'heading3', view: 'h3', title: 'Heading 3' }
    - { model: 'heading4', view: 'h4', title: 'Heading 4' }

Copied!

It is also possible to set a class for a heading by default (for example, <h2 class="h2">):

heading:
  options:
     - { model: 'heading2', view: { name: 'h2', classes: 'h2' }, title: 'Heading 2' }
     - { model: 'heading3', view: { name: 'h3', classes: 'h3' }, title: 'Heading 3' }
     - { model: 'heading4', view: { name: 'h4', classes: 'h4' }, title: 'Heading 4' }

Copied!

To be able to reset a heading to a paragraph, add also the paragraph option:

heading:
  options:
     - { model: 'paragraph', title: 'Paragraph' }
     - { model: 'heading2', view 'h2', title: 'Heading 2' }
     # ...

Copied!

A title can also be localized with LLL:EXT:....

editor.config.style

Defines styles available in the style dropdown.

Example:

style:
  definitions:
    - { name: "Lead", element: "p", classes: ['lead'] }
    - { name: "Multiple", element: "p", classes: ['first', 'second'] }

Copied!

editor.config.importModules

Imports custom CKEditor plugins. See EXT:rte_ckeditor/Configuration/RTE/Editor/Plugins.yaml (GitHub) or How do I create a custom plugin? for examples.

allowedOptions

This string contains a comma separated list of additional attributes used in the Link Browser. Available field lists can be found in EXT:backend/Classes/Controller/AbstractLinkBrowserController.php (GitHub), method getLinkAttributeFieldDefinitions().

Note that the attributes target, class and rel are displayed differently depending on whether the Link Browser was opened for a TCA element, or a RTE element. See EXT:rte_ckeditor/Classes/Controller/BrowseLinksController.php (GitHub) in method getLinkAttributeFieldDefinitions().

Valid attributes keys are:

target

If set, an input box for link target (for example "_blank") is available.

title

If set, entering the link title is available.

class

If set, allowing to enter a CSS class name for the link is available. This needs to match the CSS classes made available to the CKEDitor instance.

params

If set, additional parameters are allowed to be set for a link.

rel

If set, relations (rel attribute) for links can be set.

To set all of them, you can use:

allowedOptions: 'target,title,class,params,rel'

To remove all options you can use an empty string:

allowedOptions: ''

allowedTypes

This string contains a comma-separated list of all allowed Link Types for the Link Browser. These are currently:

• page
• url
• file
• folder
• email
• ... any custom Link Type

allowedTypes: 'page,url,file,folder,email,customType'

To remove all types you can use an empty string:

allowedTypes: ''

classesAnchor

This is a sub-array of default CSS classes and target attributes, per Link Type:

classesAnchor:
  - { class: "customPageCssClass", type: "page", target: "" }
  - { class: "customUrlCssClass", type: "url", target: "_blank" }
  - { class: "customFileCssClass", type: "file", target: "_parent" }
  - { class: "customFolderCssClass", type: "folder" }
  - { class: "customTelephoneCssClass", type: "telephone" }
  - { class: "customEmailCssClass", type: "email" }

Note that the available CSS class here must also be part of the buttons.link.properties.class.allowedClasses definition.

buttons.link

This structure defines both global options as well as Link Type-specific options:

buttons.link.options.removeItems

Can be set to exclude certain Link Types:

buttons:
  link:
    options:
      removeItems: 'telephone'

buttons.link.relAttribute.enabled

If the allowedOptions string list contains rel for setting relation attributes, this option must also be enabled:

buttons:
  link:
    relAttribute:
      enabled: true

buttons.link.queryParametersSelector.enabled

If the allowedOptions string list contains params for setting URI argument attributes, this option must also be enabled:

buttons:
  link:
    queryParametersSelector:
      enabled: true

buttons.link.targetSelector.disabled

If the allowedOptions string list contains target, a dropdown is displayed by default. If you want to hide it, you must set this option to true:

buttons:
  link:
    targetSelector:
      disabled: true

buttons.link.properties.class.required

A CSS class selection can be forced, so that it may not be empty:

buttons:
  link:
    properties:
      class:
        required: true

buttons.link.properties.class.allowedClasses

This is the most vital CSS class selection list, based on a comma-separated string naming all CSS classes that are allowed. Default CSS classes per Link Type can only be selected, if they are part of this list.

The names of the CSS classes can be adjusted via the classes top-level configuration hierarchy (see below)

buttons:
  link:
    properties:
      class:
        allowedClasses: 'globalCss1,globalCss1,CustomPageCssClass'

buttons.link.[linkType].properties.class.default

For each Link Type, a default CSS class can be defined, using the name of the Link Type as a key:

buttons:
  link:
    telephone:
      class:
        default: "customTelephoneCssClass"
    email:
      class:
        default: "customEmailCssClass"

Note that the CSS class listed here must also be contained in buttons.link.properties.class.allowedClasses.

classes.[CssClassName]

The list of CSS classes defined in buttons.link.properties.class.allowedClasses can set a custom label as well as a styling the select option. Note that styling select options does not work in every browser, and is not suggested to use.

The name of the structure key must match the CSS class name, with a sub-structure defining name (the actual label) and value (the possible CSS styling of the option inside the dropdown):

classes:
  globalCss1:
    name: "A Label for globalCss1"
    value: "color: red"
  customEmailCssClass:
    name: "An email-specific class for VIPs"