ckeditor5 1.0.5 → 1.1.0

data/README.md

@@ -8,6 +8,10 @@
 
 Unofficial CKEditor 5 Ruby on Rails integration gem. Provides seamless integration of CKEditor 5 with Rails applications through web components and helper methods.
 
+<p align="center">
+  <img src="docs/intro-classic-editor.png" alt="CKEditor 5 Classic Editor in Ruby on Rails application">
+</p>
+
 ## Installation 🛠️
 
 Add this line to your application's Gemfile:
@@ -16,21 +20,33 @@ Add this line to your application's Gemfile:
 gem 'ckeditor5'
 ```
 
-Usage in your Rails application:
+In your config:
+
+```rb
+# config/initializers/ckeditor5.rb
+
+CKEditor5::Rails::Engine.configure do |config|
+  config.presets.override :default do
+    version '43.3.0'
+  end
+end
+```
+
+In your view:
 
 ```erb
 <!-- app/views/demos/index.html.erb -->
 
 <% content_for :head do %>
-  <%= ckeditor5_assets version: '43.2.0', translations: [:pl, :es] %>
+  <%= ckeditor5_assets %>
+  <!-- or using inline config: ckeditor5_assets version: '43.3.0', premium: false -->
 <% end %>
 
-<%= ckeditor5_editor style: 'width: 600px' %>
+<%= ckeditor5_editor style: 'width: 600px', initial_data: '<YOUR DATA>' %>
+<!-- or using inline config: ckeditor5_editor type: :classic, config: { toolbar: [:Bold, :Italic] }, ... -->
 ```
 
-Effect:
-
-![CKEditor 5 Classic Editor in Ruby on Rails application](docs/intro-classic-editor.png)
+Voilà! You have CKEditor 5 integrated with your Rails application. 🎉
 
 ## Table of Contents 📚
 
@@ -39,13 +55,20 @@ Effect:
   - [Table of Contents 📚](#table-of-contents-)
   - [Presets 🎨](#presets-)
     - [Available Configuration Methods ⚙️](#available-configuration-methods-️)
-      - [`shape(type)` method](#shapetype-method)
-      - [`plugins(*names)` method](#pluginsnames-method)
-      - [`toolbar(*items, should_group_when_full: true)` method](#toolbaritems-should_group_when_full-true-method)
+      - [`version(version)` method](#versionversion-method)
+      - [`gpl` method](#gpl-method)
+      - [`license_key(key)` method](#license_keykey-method)
+      - [`premium` method](#premium-method)
+      - [`translations(*languages)` method](#translationslanguages-method)
+      - [`ckbox` method](#ckbox-method)
+      - [`type(type)` method](#typetype-method)
+      - [`toolbar(*items, should_group_when_full: true, &block)` method](#toolbaritems-should_group_when_full-true-block-method)
       - [`menubar(visible: true)` method](#menubarvisible-true-method)
       - [`language(ui, content:)` method](#languageui-content-method)
       - [`configure(name, value)` method](#configurename-value-method)
       - [`plugin(name, premium:, import_name:)` method](#pluginname-premium-import_name-method)
+      - [`plugins(*names, **kwargs)` method](#pluginsnames-kwargs-method)
+      - [`inline_plugin(name, code)` method](#inline_pluginname-code-method)
   - [Including CKEditor 5 assets 📦](#including-ckeditor-5-assets-)
     - [Lazy loading 🚀](#lazy-loading-)
     - [GPL usage 🆓](#gpl-usage-)
@@ -56,31 +79,41 @@ Effect:
     - [Inline editor 📝](#inline-editor-)
     - [Balloon editor 🎈](#balloon-editor-)
     - [Decoupled editor 🌐](#decoupled-editor-)
+  - [How to access editor instance? 🤔](#how-to-access-editor-instance-)
+  - [Events fired by the editor 🔊](#events-fired-by-the-editor-)
+    - [`editor-ready` event](#editor-ready-event)
+    - [`editor-error` event](#editor-error-event)
+  - [Common Tasks and Solutions 💡](#common-tasks-and-solutions-)
+    - [Setting Initial Content 📝](#setting-initial-content-)
+    - [Setting Editor Language 🌐](#setting-editor-language-)
+    - [Integrating with Forms 📋](#integrating-with-forms-)
+      - [Rails form builder integration](#rails-form-builder-integration)
+      - [Simple form integration](#simple-form-integration)
+    - [Custom Styling 🎨](#custom-styling-)
+    - [Custom plugins 🧩](#custom-plugins-)
   - [License 📜](#license-)
 
 ## Presets 🎨
 
 Presets are predefined configurations of CKEditor 5, allowing quick setup with specific features. The gem includes a `:default` preset with common features like bold, italic, underline, and link for the classic editor.
 
-You can override the default preset or create your own by defining a new preset in the `config/initializers/ckeditor5.rb` file using the `config.presets.define` method.
-
-The example below shows how to define a custom preset with a classic editor and a custom toolbar:
+You can create your own by defining it in the `config/initializers/ckeditor5.rb` file using the `config.presets.define` method. The example below illustrates the setup of a custom preset with a classic editor and a custom toolbar:
 
 ```rb
 # config/initializers/ckeditor5.rb
 
 CKEditor5::Rails::Engine.configure do |config|
   config.presets.define :custom
-    shape :classic
+    gpl
+    type :classic
 
     menubar
-
     toolbar :undo, :redo, :|, :heading, :|, :bold, :italic, :underline, :|,
-            :link, :insertImage, :ckbox, :mediaEmbed, :insertTable, :blockQuote, :|,
+            :link, :insertImage, :mediaEmbed, :insertTable, :blockQuote, :|,
             :bulletedList, :numberedList, :todoList, :outdent, :indent
 
     plugins :AccessibilityHelp, :Autoformat, :AutoImage, :Autosave,
-            :BlockQuote, :Bold, :CKBox, :CKBoxImageEdit, :CloudServices,
+            :BlockQuote, :Bold, :CloudServices,
             :Essentials, :Heading, :ImageBlock, :ImageCaption, :ImageInline,
             :ImageInsert, :ImageInsertViaUrl, :ImageResize, :ImageStyle,
             :ImageTextAlternative, :ImageToolbar, :ImageUpload, :Indent,
@@ -89,11 +122,15 @@ CKEditor5::Rails::Engine.configure do |config|
             :SelectAll, :Table, :TableCaption, :TableCellProperties,
             :TableColumnResize, :TableProperties, :TableToolbar,
             :TextTransformation, :TodoList, :Underline, :Undo, :Base64UploadAdapter
+
+    configure :image, {
+      toolbar: ['imageTextAlternative', 'imageStyle:inline', 'imageStyle:block', 'imageStyle:side']
+    }
   end
 end
 ```
 
-In order to override existing presets, you can use the `config.presets.override` method. The method takes the name of the preset you want to override and a block with the new configuration. In example below, we override the `:default` preset to hide the menubar.
+In order to override existing presets, you can use the `config.presets.override` method. The method takes the name of the preset you want to override and a block with the old configuration. The example below shows how to hide the menubar in the default preset:
 
 ```rb
 # config/initializers/ckeditor5.rb
@@ -105,46 +142,132 @@ CKEditor5::Rails::Engine.configure do |config|
 end
 ```
 
-You can generate your preset using the CKEditor 5 [online builder](https://ckeditor.com/ckeditor-5/online-builder/). After generating the configuration, you can copy it to the `config/initializers/ckeditor5.rb` file.
+Configuration of the editor can be complex, and it's recommended to use the CKEditor 5 [online builder](https://ckeditor.com/ckeditor-5/online-builder/) to generate the configuration. It allows you to select the features you want to include and generate the configuration code in JavaScript format.  Keep in mind that you need to convert the JavaScript configuration to Ruby format before using it in this gem.
 
 ### Available Configuration Methods ⚙️
 
 <details>
   <summary>Expand to show available methods 📖</summary>
 
-#### `shape(type)` method
+#### `version(version)` method
 
-Defines the type of editor. Available options:
+Defines the version of CKEditor 5 to be used. The example below shows how to set the version to `43.2.0`:
 
-- `:classic` - classic edytor
-- `:inline` - inline editor
-- `:decoupled` - decoupled editor
-- `:balloon` - balloon editor
-- `:multiroot` - editor with multiple editing areas
+```rb
+# config/initializers/ckeditor5.rb
+
+config.presets.define :custom do
+  # ... other configuration
+
+  version '43.2.0'
+end
+```
+
+#### `gpl` method
+
+Defines the license of CKEditor 5. The example below shows how to set the license to GPL:
+
+```rb
+# config/initializers/ckeditor5.rb
+
+config.presets.define :custom do
+  # ... other configuration
+
+  gpl
+end
+```
+
+#### `license_key(key)` method
 
-The example below shows how to define a multiroot editor:
+Defines the license key of CKEditor 5. It calls `premium` method internally. The example below shows how to set the license key:
 
 ```rb
 # config/initializers/ckeditor5.rb
 
 config.presets.define :custom do
-  shape :multiroot
+  # ... other configuration
+
+  license_key 'your-license-key'
 end
 ```
 
-#### `plugins(*names)` method
+#### `premium` method
 
-Defines the plugins to be included in the editor. You can specify multiple plugins by passing their names as arguments.
+Defines if premium package should be included in JS assets. The example below shows how to add `ckeditor5-premium-features` to import maps:
 
 ```rb
 # config/initializers/ckeditor5.rb
 
 config.presets.define :custom do
-  plugins :Bold, :Italic, :Underline, :Link
+  # ... other configuration
+
+  premium
 end
 ```
 
-#### `toolbar(*items, should_group_when_full: true)` method
+#### `translations(*languages)` method
+
+Defines the translations of CKEditor 5. You can pass the language codes as arguments. The example below shows how tell integration to fetch Polish and Spanish translations:
+
+```rb
+# config/initializers/ckeditor5.rb
+
+config.presets.define :custom do
+  # ... other configuration
+
+  translations :pl, :es
+end
+```
+
+⚠️ You need to use `language` method to set the default language of the editor, as the `translations` only fetch the translations files and makes them available to later use.
+
+```rb
+# config/initializers/ckeditor5.rb
+
+config.presets.define :custom do
+  translations :pl
+
+  language :pl
+end
+```
+
+#### `ckbox` method
+
+Defines the CKBox plugin to be included in the editor. The example below shows how to include the CKBox plugin:
+
+```rb
+# config/initializers/ckeditor5.rb
+
+config.presets.define :custom do
+  # ... other configuration
+
+  ckbox '2.5.4', theme: :lark
+end
+```
+
+#### `type(type)` method
+
+Defines the type of editor. Available options:
+
+- `:classic` - classic edytor
+- `:inline` - inline editor
+- `:decoupled` - decoupled editor
+- `:balloon` - balloon editor
+- `:multiroot` - editor with multiple editing areas
+
+The example below sets the editor type to `multiroot` in the custom preset:
+
+```rb
+# config/initializers/ckeditor5.rb
+
+config.presets.define :custom do
+  # ... other configuration
+
+  type :multiroot
+end
+```
+
+#### `toolbar(*items, should_group_when_full: true, &block)` method
 
 Defines the toolbar items. You can use predefined items like `:undo`, `:redo`, `:|` or specify custom items. There are a few special items:
 
@@ -167,6 +290,21 @@ end
 
 Keep in mind that the order of items is important, and you should install the corresponding plugins. You can find the list of available plugins in the [CKEditor 5 documentation](https://ckeditor.com/docs/ckeditor5/latest/framework/architecture/plugins.html).
 
+If you want to add or prepend items to the existing toolbar, you can use the block syntax:
+
+```rb
+# config/initializers/ckeditor5.rb
+
+config.presets.override :default do
+  # ... other configuration
+
+  toolbar do
+    append :selectAll, :|, :selectAll, :selectAll
+    # Or prepend: prepend :selectAll, :|, :selectAll, :selectAll
+  end
+end
+```
+
 #### `menubar(visible: true)` method
 
 Defines the visibility of the menubar. By default, it's set to `true`.
@@ -241,7 +379,7 @@ config.presets.define :custom do
 end
 ```
 
-In order to import a plugin from a custom package, you can pass the `import_name` keyword argument:
+In order to import a plugin from a custom ESM package, you can pass the `import_name` keyword argument:
 
 ```rb
 # config/initializers/ckeditor5.rb
@@ -253,20 +391,71 @@ config.presets.define :custom do
 end
 ```
 
+In order to import a plugin from a custom Window entry, you can pass the `window_name` keyword argument:
+
+```rb
+# config/initializers/ckeditor5.rb
+
+config.presets.define :custom do
+  # ... other configuration
+
+  plugin :YourPlugin, window_name: 'YourPlugin'
+end
+```
+
+#### `plugins(*names, **kwargs)` method
+
+Defines the plugins to be included in the editor. You can specify multiple plugins by passing their names as arguments. The keyword arguments are identical to the configuration of the `plugin` method defined below.
+
+```rb
+# config/initializers/ckeditor5.rb
+
+config.presets.define :custom do
+  # ... other configuration
+
+  plugins :Bold, :Italic, :Underline, :Link
+end
+```
+
+#### `inline_plugin(name, code)` method
+
+Use with caution as this is an inline definition of the plugin code, and you can define a custom class or function for the plugin here. The example below shows how to define a custom plugin that highlights the text:
+
+```rb
+# config/initializers/ckeditor5.rb
+
+config.presets.define :custom do
+  # ... other configuration
+
+  inline_plugin :MyCustomPlugin, <<~JS
+    import { Plugin } from 'ckeditor5';
+
+    export default class MyCustomPlugin extends Plugin {
+      static get pluginName() {
+        return 'MyCustomPlugin';
+      }
+
+      init() {
+        // ... Your plugin code
+      }
+    }
+  JS
+end
+```
 </details>
 
 ## Including CKEditor 5 assets 📦
 
-To include CKEditor 5 assets in your application, you can use the `ckeditor5_assets` helper method. This method takes the version of CKEditor 5 as an argument and includes the necessary assets. It allows you to specify custom translations to be included.
+To include CKEditor 5 assets in your application, you can use the `ckeditor5_assets` helper method. This method takes the version of CKEditor 5 as an argument and includes the necessary resources of the editor. Depending on the specified configuration, it includes the JS and CSS assets from the official CKEditor 5 CDN or one of the popular CDNs.
 
-Keep in mind that you need to include the assets in the `head` section of your layout. In examples below, we use `content_for` to include the assets in the `head` section.
+Keep in mind that you need to include the helper result in the `head` section of your layout. In examples below, we use `content_for` helper to include the assets in the `head` section of the view.
 
 ### Lazy loading 🚀
 
 <details>
   <summary>Loading JS and CSS Assets</summary>
 
-All JS assets defined by the `ckeditor5_assets` helper method are loaded asynchronously. It means that the assets are loaded in the background without blocking the rendering of the page. However, the CSS assets are loaded synchronously to prevent the flash of unstyled content and ensure that the editor is styled correctly.
+All JS assets defined by the `ckeditor5_assets` helper method are loaded **asynchronously**. It means that the assets are loaded in the background without blocking the rendering of the page. However, the CSS assets are loaded **synchronously** to prevent the flash of unstyled content and ensure that the editor is styled correctly.
 
 It has been achieved by using web components, together with import maps, which are supported by modern browsers. The web components are used to define the editor and its plugins, while the import maps are used to define the dependencies between the assets.
 
@@ -274,7 +463,7 @@ It has been achieved by using web components, together with import maps, which a
 
 ### GPL usage 🆓
 
-If you want to use CKEditor 5 under the GPL license, you can include the assets using the `ckeditor5_assets` helper method with the `version` keyword argument. The example below shows how to include the assets for version `43.3.0`:
+If you want to use CKEditor 5 under the GPL license, you can include the assets using the `ckeditor5_assets` without passing any arguments. However you can pass the `version` keyword argument with the version of CKEditor 5 you want to use:
 
 ```erb
 <!-- app/views/demos/index.html.erb -->
@@ -286,6 +475,28 @@ If you want to use CKEditor 5 under the GPL license, you can include the assets
 
 It'll include the necessary assets for the GPL license from one of the most popular CDNs. In our scenario, we use the `jsdelivr` CDN which is the default one.
 
+Version is optional as long as you defined it in the `config/initializers/ckeditor5.rb` file. If you want to use the default version, you can omit the `version` keyword argument:
+
+```erb
+<!-- app/views/demos/index.html.erb -->
+
+<% content_for :head do %>
+  <%= ckeditor5_assets %>
+<% end %>
+```
+
+Set the version in the `config/initializers/ckeditor5.rb` file:
+
+```rb
+# config/initializers/ckeditor5.rb
+
+CKEditor5::Rails::Engine.configure do
+  presets.override :default do
+    version '43.3.0'
+  end
+end
+```
+
 In order to use `unpkg` CDN, you can pass the `cdn` keyword argument with the value `:unpkg`:
 
 ```erb
@@ -349,7 +560,7 @@ In this scenario, the assets are included from the official CKEditor 5 CDN which
 
 ## Editor placement 🏗️
 
-The `ckeditor5_editor` helper renders CKEditor 5 instances in your views. Before using it, ensure you've included the necessary assets in your page's head section.
+The `ckeditor5_editor` helper renders CKEditor 5 instances in your views. Before using it, ensure you've included the necessary assets in your page's head section otherwise the editor won't work as there are no CKEditor 5 JavaScript and CSS files loaded.
 
 ### Classic editor 📝
 
@@ -365,7 +576,7 @@ The example below shows how to include the classic editor in your view:
 <!-- app/views/demos/index.html.erb -->
 
 <% content_for :head do %>
-  <%= ckeditor5_assets version: '43.3.0' %>
+  <%= ckeditor5_assets %>
 <% end %>
 
 <%= ckeditor5_editor style: 'width: 600px' %>
@@ -379,7 +590,7 @@ While example above uses predefined `:default` preset, you can use your custom p
 <!-- app/views/demos/index.html.erb -->
 
 <% content_for :head do %>
-  <%= ckeditor5_assets version: '43.3.0' %>
+  <%= ckeditor5_assets %>
 <% end %>
 
 <%= ckeditor5_editor preset: :custom, style: 'width: 600px' %>
@@ -391,7 +602,7 @@ If your configuration is even more complex, you can pass the `config` and `type`
 <!-- app/views/demos/index.html.erb -->
 
 <% content_for :head do %>
-  <%= ckeditor5_assets version: '43.3.0' %>
+  <%= ckeditor5_assets %>
 <% end %>
 
 <%= ckeditor5_editor type: :classic, config: { plugins: [:Bold, :Italic], toolbar: [:Bold, :Italic] }, style: 'width: 600px' %>
@@ -403,7 +614,7 @@ If you want to override the configuration of the editor specified in default or
 <!-- app/views/demos/index.html.erb -->
 
 <% content_for :head do %>
-  <%= ckeditor5_assets version: '43.3.0' %>
+  <%= ckeditor5_assets %>
 <% end %>
 
 <%= ckeditor5_editor extra_config: { toolbar: [:Bold, :Italic] }, style: 'width: 600px' %>
@@ -425,7 +636,7 @@ If you want to use a multiroot editor, you can pass the `type` keyword argument
 <!-- app/views/demos/index.html.erb -->
 
 <% content_for :head do %>
-  <%= ckeditor5_assets version: '43.2.0' %>
+  <%= ckeditor5_assets %>
 <% end %>
 
 <%= ckeditor5_editor type: :multiroot, style: 'width: 600px' do %>
@@ -454,7 +665,7 @@ If you want to use an inline editor, you can pass the `type` keyword argument wi
 <!-- app/views/demos/index.html.erb -->
 
 <% content_for :head do %>
-  <%= ckeditor5_assets version: '43.2.0' %>
+  <%= ckeditor5_assets %>
 <% end %>
 
 <%= ckeditor5_editor type: :inline, style: 'width: 600px' %>
@@ -472,7 +683,7 @@ If you want to use a balloon editor, you can pass the `type` keyword argument wi
 <!-- app/views/demos/index.html.erb -->
 
 <% content_for :head do %>
-  <%= ckeditor5_assets version: '43.2.0' %>
+  <%= ckeditor5_assets %>
 <% end %>
 
 <%= ckeditor5_editor type: :balloon, style: 'width: 600px' %>
@@ -488,60 +699,304 @@ If you want to use a decoupled editor, you can pass the `type` keyword argument
 
 ```erb
 <% content_for :head do %>
-  <%= ckeditor5_assets version: '43.2.0', translations: [:pl, :es] %>
+  <%= ckeditor5_assets %>
 <% end %>
 
-<style>
-  .menubar-container,
-  .editable-container,
-  .toolbar-container {
-    position: relative;
-    border: 1px solid red;
-  }
+<%= ckeditor5_editor type: :decoupled, style: 'width: 600px' do %>
+  <div class="menubar-container">
+    <%= ckeditor5_menubar %>
+  </div>
 
-  .menubar-container::after,
-  .editable-container::after,
-  .toolbar-container::after {
-    content: attr(class);
-    position: absolute;
-    background: red;
-    color: #fff;
-    top: 0;
-    right: 0;
-    font: 10px/2 monospace;
-    padding: .1em .3em;
-  }
+  <div class="toolbar-container">
+    <%= ckeditor5_toolbar %>
+  </div>
+
+  <div class="editable-container">
+    <%= ckeditor5_editable %>
+  </div>
+<% end %>
+```
+
+## How to access editor instance? 🤔
+
+You can access the editor instance using plain HTML and JavaScript, as CKEditor 5 is a web component with defined `instance`, `instancePromise` and `editables` properties.
+
+For example:
+
+```erb
+<!-- app/views/demos/index.html.erb -->
+
+<% content_for :head do %>
+  <%= ckeditor5_assets %>
+<% end %>
+
+<%= ckeditor5_editor style: 'width: 600px', id: 'editor' %>
+```
+
+⚠️ Direct access of `instance` property of the web component. Keep in mind it's unsafe and may cause issues if the editor is not loaded yet.
+
+```js
+document.getElementById('editor').instance
+```
+
+👌 Accessing the editor instance using `instancePromise` property. It's a promise that resolves to the editor instance when the editor is ready.
+
+```js
+document.getElementById('editor').instancePromise.then(editor => {
+  console.log(editor);
+});
+```
+
+✅ Accessing the editor through the `runAfterEditorReady` helper method. It's a safe way to access the editor instance when the editor is ready.
+
+```js
+document.getElementById('editor').runAfterEditorReady(editor => {
+  console.log(editor);
+});
+```
+
+## Events fired by the editor 🔊
+
+### `editor-ready` event
+
+The event is fired when the initialization of the editor is completed. You can listen to it using the `editor-ready` event.
+
+```js
+document.getElementById('editor').addEventListener('editor-ready', () => {
+  console.log('Editor is ready');
+});
+```
+
+### `editor-error` event
+
+The event is fired when the initialization of the editor fails. You can listen to it using the `editor-error` event.
 
-  .menubar-container,
-  .toolbar-container {
-    padding: 1em;
+```js
+document.getElementById('editor').addEventListener('editor-error', () => {
+  console.log('Editor has an error');
+});
+```
+
+## Common Tasks and Solutions 💡
+
+This section covers frequent questions and scenarios when working with CKEditor 5 in Rails applications.
+
+### Setting Initial Content 📝
+
+```erb
+<%= ckeditor5_editor initial_data: "<p>Initial content</p>" %>
+```
+
+### Setting Editor Language 🌐
+
+```rb
+config.presets.override :default do
+  translations :pl, :es
+  language :pl
+end
+```
+
+### Integrating with Forms 📋
+
+#### Rails form builder integration
+
+```erb
+<%= form_for @post do |f| %>
+  <%= f.label :content %>
+  <%= f.ckeditor5 :content, required: true, style: 'width: 700px', initial_data: 'Hello World!' %>
+<% end %>
+```
+
+#### Simple form integration
+
+```erb
+<%= simple_form_for :demo, url: '/demos', html: { novalidate: false } do |f| %>
+  <div class="form-group">
+    <%= f.input :content, as: :ckeditor5, initial_data: 'Hello, World 12!', input_html: { style: 'width: 600px' }, required: true %>
+  </div>
+
+  <div class="form-group mt-3">
+    <%= f.button :submit, 'Save', class: 'btn btn-primary' %>
+  </div>
+<% end %>
+```
+
+### Custom Styling 🎨
+
+```erb
+<%= ckeditor5_editor style: 'height: 400px; margin: 20px;' %>
+```
+
+### Custom plugins 🧩
+
+You can create custom plugins for CKEditor 5 using the `inline_plugin` method. It allows you to define a custom class or function inside your preset configuration.
+
+The example below shows how to define a custom plugin that allows toggling the highlight of the selected text:
+
+![CKEditor 5 Custom Highlight Plugin in Ruby on Rails application](docs/custom-highlight-plugin.png)
+
+```rb
+# config/initializers/ckeditor5.rb
+
+config.presets.define :custom do
+  # ... other configuration
+
+  # 1. You can define it inline like below or in a separate file.
+
+  # In case if plugin is located in external file (recommended), you can simply import it:
+
+  # inline_plugin :MyCustomPlugin, <<~JS
+  #  import MyPlugin from 'app/javascript/custom_plugins/highlight.js';
+  #  export default MyPlugin;
+  # JS
+
+  # 2. You can also use "window_name" option to import plugin from window object:
+
+  # plugin :MyPlugin, window_name: 'MyPlugin'
+
+  # 3. Create JavaScript file in app/javascript/custom_plugins/highlight.js:
+  # You can also use "plugin" to import plugin from file using 'import_name' option.
+  # Your `my-custom-plugin` must be present in import map.
+
+  # plugin :MyCustomPlugin, import_name: 'my-custom-plugin'
+
+  # 4 Create JavaScript file in app/javascript/custom_plugins/highlight.js:
+
+  # In Ruby initializer you can also load plugin code directly from file:
+  plugin :MyCustomPlugin, File.read(
+    Rails.root.join('app/javascript/custom_plugins/highlight.js')
+  )
+
+  # 5. Or even define it inline:
+  # plugin :MyCustomPlugin,  <<~JS
+  #    import { Plugin } from 'ckeditor5';
+  #
+  #    export default class MyCustomPlugin extends Plugin {
+  #      // ...
+  #    }
+  # JS
+
+  # Add item to beginning of the toolbar.
+  toolbar do
+    prepend :highlight
+  end
+end
+```
+
+<details>
+  <summary>Example of Custom Highlight Plugin 🎨</summary>
+
+```js
+// app/javascript/custom_plugins/highlight.js
+import { Plugin, Command, ButtonView } from 'ckeditor5';
+
+export default class MyCustomPlugin extends Plugin {
+  static get pluginName() {
+    return 'MyCustomPlugin';
   }
 
-  .editable-container {
-    padding: 3em;
-    overflow-y: scroll;
-    max-height: 300px;
+  init() {
+    const editor = this.editor;
+
+    // Define schema for highlight attribute
+    editor.model.schema.extend('$text', { allowAttributes: 'highlight' });
+
+    // Define conversion between model and view
+    editor.conversion.attributeToElement({
+      model: 'highlight',
+      view: {
+        name: 'span',
+        styles: {
+          'background-color': 'yellow'
+        }
+      }
+    });
+
+    // Create command that handles highlighting logic
+    // Command pattern is used to encapsulate all the logic related to executing an action
+    const command = new HighlightCommand(editor);
+
+    // Register command in editor
+    editor.commands.add('highlight', command);
+
+    // Add UI button
+    editor.ui.componentFactory.add('highlight', locale => {
+      const view = new ButtonView(locale);
+
+      // Bind button state to command state using bind method
+      // bind() allows to sync button state with command state automatically
+      view.bind('isOn').to(command, 'value');
+
+      view.set({
+        label: 'Highlight',
+        withText: true,
+        tooltip: true
+      });
+
+      view.on('execute', () => {
+        editor.execute('highlight');
+        editor.editing.view.focus();
+      });
+
+      return view;
+    });
+  }
+}
+
+// Command class that handles the highlight feature
+// isEnabled property determines if command can be executed
+class HighlightCommand extends Command {
+  execute() {
+    const model = this.editor.model;
+    const selection = model.document.selection;
+
+    model.change(writer => {
+      const ranges = model.schema.getValidRanges(selection.getRanges(), 'highlight');
+
+      for (const range of ranges) {
+        if (this.value) {
+          writer.removeAttribute('highlight', range);
+        } else {
+          writer.setAttribute('highlight', true, range);
+        }
+      }
+    });
   }
 
-  .editable-container .ck-editor__editable {
-    min-height: 21cm;
-    padding: 2em;
-    border: 1px #D3D3D3 solid;
-    border-radius: var(--ck-border-radius);
-    background: white;
-    box-shadow: 0 0 5px rgba(0, 0, 0, 0.1);
+  refresh() {
+    const model = this.editor.model;
+    const selection = model.document.selection;
+    const isAllowed = model.schema.checkAttributeInSelection(selection, 'highlight');
+
+    // Set if command is enabled based on schema
+    this.isEnabled = isAllowed;
+    this.value = this.#isHighlightedNodeSelected();
   }
-</style>
 
-<%= ckeditor5_editor type: :decoupled, style: 'width: 600px' do %>
-  <div class="menubar-container"><%= ckeditor5_menubar %></div>
-  <br>
-  <div class="toolbar-container"><%= ckeditor5_toolbar %></div>
-  <br>
-  <div class="editable-container"><%= ckeditor5_editable %></div>
-<% end %>
+  // Check if the highlighted node is selected.
+  #isHighlightedNodeSelected() {
+    const { model } = this.editor
+    const { schema } = model
+    const selection = model.document.selection
+
+    if (selection.isCollapsed) {
+      return selection.hasAttribute('highlight')
+    }
+
+    return selection.getRanges().some(range =>
+      Array
+        .from(range.getItems())
+        .some(item =>
+          schema.checkAttribute(item, 'highlight') &&
+          item.hasAttribute('highlight')
+        )
+    );
+  }
+}
 ```
 
+</details>
+
 ## License 📜
 
 The MIT License (MIT)