strapi-plugin-ckeditor-strapi-v5 v1.0.1

👋 Get Started

• Features
• Installation
• Usage
• Configuration
• Contributing
• Requirements

✨ Features

• Media library integration
• Responsive images support
• Strapi theme switching support
• Supports custom styles for the editor
• Supports i18n and different UI translations
• A few predefined, modifiable editor configurations
• Allows custom editor configrations
• Plugins extensibility

🔧 Installation

Add the package to your Strapi application:

npm install @_sh/strapi-plugin-ckeditor

or

yarn add @_sh/strapi-plugin-ckeditor

Then build the app:

npm run build

or

yarn build

✍️ Usage

1. Go to the Content-Type Builder -> Add another field -> switch to custom

2. Click on CKEditor 5

3. Choose the editor version you want

Default versions:

⚙️ Configuration

The plugin is based on the Strapi Custom Field API and the CKEditor5 DLL build.

It is highly recommended to explore the official CKEditor5 documentation.

The plugin configuration should be defined in your-app/config/ckeditor.txt.

The plugin provides three editor configurations by default. Each configuration includes a set of plugins, settings, and styles.

You can select the configuration you need in the Content-Type Builder. Each configuration can be modified in the config file, and you can also create new ones.

Config structure looks like this:

globalThis.CKEditorConfig = {
    configsOverwrite:bool,
    themeOverwrite:bool,
    configs:{
        toolbar:{...},
        toolbarBalloon:{...},
        blockBalloon:{...},
        customEditorVersion1:{...},
        customEditorVersion2:{...}
        ...
    }
    theme:{...}
}

Every configuration in the configs object contains three properties:

1. field (object) Registers this configuration version in the Admin panel.
2. styles (string) Styles applied to the editor in this version.
3. editorConfig (object) The CKEditor configuration.

The theme object is used to modify the default global theme of the plugin. It contains four properties:

1. common (string) Styles applied to the editor to ensure proper appearance of the input.
2. light (string) Styles applied to the editor when Strapi is in light mode.
3. dark (string) Styles applied to the editor when Strapi is in dark mode.
4. additional (string) Additional styles to further enhance the editors appearance.

By default, everything defined in the user’s configuration is merged with the default configuration object. These two properties allow you to prevent this behavior:

1. configsOverwrite (bool)
2. themeOverwrite (bool)

Since Strapi uses i18n for translation, the ignorei18n property is added to the editorConfig.language object. This property allows you to manually set the content language, bypassing i18n. The language object looks like this:

language:{
    ignorei18n (bool),
    ui (string),
    content (string)
}

The language determination follows this logic:

• Plugin UI language: language.ui -> preferred language -> 'en'

• Content language: ignorei18n ? language.content : i18n -> language.ui

Example of adding a new editor configuration:

globalThis.CKEditorConfig = {
    configs:{
        myCustomVariant:{
            field: {
                key: "myCustomVariant",
                value: "myCustomVariant",
                metadatas: {
                    intlLabel: {
                        id: "ckeditor5.preset.myCustomVariant.label",
                        defaultMessage: "My custom variant",
                    },
                },
            },
            editorConfig:{
                plugins: [
                    CKEditor5.autoformat.Autoformat,
                    CKEditor5.basicStyles.Bold,
                    CKEditor5.basicStyles.Italic,
                    CKEditor5.essentials.Essentials,
                    CKEditor5.heading.Heading,
                    CKEditor5.image.Image,
                    CKEditor5.image.ImageCaption,
                    CKEditor5.image.ImageStyle,
                    CKEditor5.image.ImageToolbar,
                    CKEditor5.image.ImageUpload,
                    CKEditor5.indent.Indent,
                    CKEditor5.link.Link,
                    CKEditor5.list.List,
                    CKEditor5.paragraph.Paragraph,
                    CKEditor5.pasteFromOffice.PasteFromOffice,
                    CKEditor5.table.Table,
                    CKEditor5.table.TableToolbar,
                    CKEditor5.table.TableColumnResize,
                    CKEditor5.table.TableCaption,
                    CKEditor5.strapiPlugins.StrapiMediaLib,
                    CKEditor5.strapiPlugins.StrapiUploadAdapter,
                ],
                toolbar: [
                    'heading',
                    '|',
                    'bold', 'italic', 'link', 'bulletedList', 'numberedList',
                    '|',
                    'strapiMediaLib', 'insertTable',
                    '|',
                    'undo', 'redo'
                ],
                heading: {
                    options: [
                        { model: 'paragraph', title: 'Paragraph', class: 'ck-heading_paragraph' },
                        { model: 'heading1', view: 'h1', title: 'Heading 1', class: 'ck-heading_heading1' },
                        { model: 'heading2', view: 'h2', title: 'Heading 2', class: 'ck-heading_heading2' },
                        { model: 'heading3', view: 'h3', title: 'Heading 3', class: 'ck-heading_heading3' },
                        { model: 'heading4', view: 'h4', title: 'Heading 4', class: 'ck-heading_heading4' },
                    ]
                },
                image: {
                    toolbar: [
                        'imageStyle:inline',
                        'imageStyle:block',
                        'imageStyle:side',
                        '|',
                        'toggleImageCaption',
                        'imageTextAlternative'
                    ]
                },
                table: {
                    contentToolbar: [
                        'tableColumn',
                        'tableRow',
                        'mergeTableCells',
                        '|',
                        'toggleTableCaption'
                    ]
                }
            }
        }
    }
}

Example of changing buttons, modifying the plugin list, and adding styles in the default toolbar configuration:

globalThis.CKEditorConfig = {
    configs:{
        toolbar:{
            styles:`
                --ck-focus-ring:3px dashed #5CB176;

                .ck.ck-content.ck-editor__editable {
                  &.ck-focused:not(.ck-editor__nested-editable) {
                    border: var(--ck-focus-ring) !important;
                  }
                }
                .ck.ck-content.ck-editor__editable.ck-rounded-corners.ck-editor__editable_inline.ck-blurred{
                  min-height: 400px;
                  max-height: 400px;
                }
                .ck.ck-content.ck-editor__editable.ck-rounded-corners.ck-editor__editable_inline.ck-focused{
                  min-height: 400px;
                  max-height: 1700px;
                }
            `,
            editorConfig:{
                plugins: [
                    CKEditor5.basicStyles.Bold,
                    CKEditor5.basicStyles.Italic,
                    CKEditor5.essentials.Essentials,
                    CKEditor5.heading.Heading,
                    CKEditor5.image.Image,
                    CKEditor5.image.ImageCaption,
                    CKEditor5.image.ImageStyle,
                    CKEditor5.image.ImageToolbar,
                    CKEditor5.link.Link,
                    CKEditor5.list.List,
                    CKEditor5.paragraph.Paragraph,
                    CKEditor5.strapiPlugins.StrapiMediaLib,
                    CKEditor5.strapiPlugins.StrapiUploadAdapter,
                ],
                toolbar: [
                    'heading',
                    '|',
                    'bold', 'italic', 'link', 'bulletedList', 'numberedList',
                    '|',
                    'strapiMediaLib', 'insertTable',
                    '|',
                    'undo', 'redo'
                ]
            }
        }
    }
}

📂 Configurations availibale by default: admin/src/components/Input/CKEditor/configs

📂 Built-in plugins: admin/src/components/Input/CKEditor/configs/base.js

📂 Default editor styles: admin/src/components/Input/CKEditor/theme

💡 To display content from an external source in your admin panel, you should configure your middlewares.js. Explore the documentation for more information

Adding plugins

Exmple of adding the Markdown plugin

Add the plugin to you Strapi application:

yarn add @ckeditor/ckeditor5-markdown-gfm

or

npm install @ckeditor/ckeditor5-markdown-gfm

Import the plugin in your-app/src/admin/app.js:

import ckeditor5Dll from "ckeditor5/build/ckeditor5-dll.js";
import ckeditor5MrkdownDll from "@ckeditor/ckeditor5-markdown-gfm/build/markdown-gfm.js";

const config = {};

const bootstrap = (app) => {};

export default {
  config,
  bootstrap,
};

Add a new configuration option to your config file at your-app/config/ckeditor.txt:

Example of a config file with the new configuration:

globalThis.CKEditorConfig = {
    configs:{
        markdown:{
            field: {
                key: "markdown",
                value: "markdown",
                metadatas: {
                  intlLabel: {
                    id: "ckeditor.preset.markdown.label",
                    defaultMessage: "Markdown version",
                  },
                },
            },
            editorConfig:{
                placeholder: 'Markdown editor',
                plugins: [
                    CKEditor5.essentials.Essentials,
                    CKEditor5.autoformat.Autoformat,
                    CKEditor5.blockQuote.BlockQuote,
                    CKEditor5.basicStyles.Bold,
                    CKEditor5.heading.Heading,
                    CKEditor5.image.Image,
                    CKEditor5.image.ImageCaption,
                    CKEditor5.image.ImageStyle,
                    CKEditor5.image.ImageToolbar,
                    CKEditor5.image.ImageUpload, 
                    CKEditor5.indent.Indent,
                    CKEditor5.basicStyles.Italic,
                    CKEditor5.link.Link,
                    CKEditor5.list.List,
                    CKEditor5.mediaEmbed.MediaEmbed,
                    CKEditor5.paragraph.Paragraph,
                    CKEditor5.table.Table,
                    CKEditor5.table.TableToolbar,
                    CKEditor5.sourceEditing.SourceEditing, 
                    CKEditor5.strapiPlugins.StrapiMediaLib,
                    CKEditor5.strapiPlugins.StrapiUploadAdapter,
                    CKEditor5.markdownGfm.Markdown,
                    CKEditor5.basicStyles.Code, 
                    CKEditor5.codeBlock.CodeBlock,
                    CKEditor5.list.TodoList,
                    CKEditor5.basicStyles.Strikethrough,
                    CKEditor5.horizontalLine.HorizontalLine
                ],
                toolbar: {
                    items: [
                        'heading',
                        '|',
                        'bold',
                        'italic',
                        'strikethrough',
                        'link',
                        '|',
                        'bulletedList',
                        'numberedList',
                        'todoList',
                        '|',
                        'code',
                        'codeBlock',
                        '|',
                        'uploadImage',
                        'strapiMediaLib',
                        'blockQuote',
                        'horizontalLine',
                        '-',
                        'sourceEditing',
                        '|',
                        'outdent',
                        'indent',
                        '|',
                        'undo',
                        'redo'
                    ],
                    shouldNotGroupWhenFull: true
                },
                image: {
                    toolbar: [ 'imageStyle:inline', 'imageStyle:block', 'imageStyle:side', '|', 'toggleImageCaption', 'imageTextAlternative' ]
                },
                codeBlock: {
                    languages: [
                        { language: 'css', label: 'CSS' },
                        { language: 'html', label: 'HTML' },
                        { language: 'javascript', label: 'JavaScript' },
                        { language: 'php', label: 'PHP' }
                    ]
                },
            }
        }
    }
}

Then rebuild the application:

npm run build

or

yarn build

🛠 Contributing

This section covers how to configure your environment if you want to contribute to this package.

To start making changes to the plugin, you first need to install the Strapi infrastructure on top of the plugin repository:

npx create-strapi-app --quickstart strapi
cd strapi

By default, Strapi does not create a plugins folder, so we need to create it:

mkdir -p src/plugins

Now we should clone this repository so we can work on it.

git clone git@github.com:nshenderov/strapi-plugin-ckeditor.git src/plugins/strapi-plugin-ckeditor

Add an entry inside the ./package.json file so we won't need to use yarn inside the plugin itself:

"workspaces": ["./src/plugins/strapi-plugin-ckeditor"]

Install dependencies:

yarn install

Now we need to register the plugin so Strapi can use it. To do that, we need to create the ./config/plugins.js file (if it doesn't already exist) and add an entry to it:

module.exports = ({ env }) => ({
  ckeditor5: {
    enabled: true,
    resolve: "./src/plugins/strapi-plugin-ckeditor"
  },
});

Rebuild the project and start the server:

yarn build
yarn develop

⚠️ Requirements

Strapi v5.0.0+

Node >=18.0.0 <=20.x.x