Tiptap RTE Extensions

15/umbraco-cms/SUMMARY.md

@@ -80,7 +80,7 @@
       * [Dropdown](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/dropdown/README.md)
       * [Rich Text Editor](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/README.md)
         * [Configuration](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/configuration.md)
-        * [Plugins](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/plugins.md)
+        * [Extensions](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/extensions.md)
         * [Blocks](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/blocks.md)
         * [Change Rich Text Editor UI](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/change-rich-text-editor-ui.md)
       * [Rich Text Editor TinyMce](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor-tinymce/README.md)

15/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/README.md

@@ -12,6 +12,9 @@ You can continue to use the [TinyMCE UI for the Rich Text Editor](../rich-text-e
 **Current limitations**
 
 The Tiptap UI currently does not support using custom styles for your rich text.
+
+Resizing media images has not been implemented yet.
+
 {% endhint %}
 
 The Rich Text Editor (RTE) Tiptap property editor is highly configurable and based on [Tiptap](https://tiptap.dev/). Depending on the configuration setup, it provides editors a lot of flexibility when working with content.
@@ -24,9 +27,9 @@ Customize everything from toolbar options to editor size to where pasted images
 
 Use Blocks to define specific parts that can be added as part of the markup of the Rich Text Editor.
 
-## [Plugins](plugins.md)
+## [Extensions](extensions.md)
 
-Extend the functionality of the Rich Text Editor with plugins.
+Extend the functionality of the Rich Text Editor with extensions.
 
 ## Data Type Definition Example
 

15/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/change-rich-text-editor-ui.md

@@ -15,7 +15,7 @@ The first step in this guide is to create a new Rich Text Editor Data Type using
 As an alternative, you can create a new Data Type using the Tiptap property editor when updating the Document Type.
 
 {% hint style="info" %}
-When swapping the UI used for the Rich Text Editor, you need to reconfigure the toolbar.
+When swapping the UI used for the Rich Text Editor, you may need to reconfigure the toolbar.
 {% endhint %}
 
 1. Navigate to the **Settings** section of the Umbraco Backoffice.

15/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/extensions.md

@@ -0,0 +1,101 @@
+---
+description: Information on how to work with Tiptap extensions in the rich text editor.
+---
+
+# Extensions
+
+The Rich Text Editor (RTE) in Umbraco is based on the open-source editor [Tiptap](https://tiptap.dev/).
+
+Out of the box, Tiptap has limited capabilities and everything is an extension by design. Basic text formatting features such as bold, italic, and underline are their own extensions. This offers great flexibility, making the rich text editor highly configurable. The implementation in Umbraco offers a wide range of built-in extensions to enhance the Tiptap editor capabilities.
+
+Using the same extension points, this article will show you how to add a custom extension to the rich text editor.
+
+## Native Tiptap extensions
+
+Tiptap has a library of supported native extensions. You can find a list of these extensions on the [Tiptap website](https://tiptap.dev/docs/editor/extensions/overview). While many of these are open source, there are also [pro extensions](https://tiptap.dev/docs/guides/pro-extensions) available for commercial subscriptions.
+
+### Tiptap extension types
+
+There are two types of extension: `tiptapExtension` and `tiptapToolbarExtension`.
+
+The `tiptapExtension` extension is used to register a native [Tiptap Extension](https://tiptap.dev/docs/editor/extensions/). These will enhance the capabilities of the rich text editor itself. For example, to enable text formatting, drag-and-drop functionality and spell-checking.
+
+The `tiptapToolbarExtension` extension adds a toolbar action that interacts with the Tiptap editor (and native Tiptap extensions).
+
+
+## Adding a native extension
+
+{% hint style="info" %}
+This example assumes that you will be creating an Umbraco package using the Vite/Lit/TypeScript setup.
+You can learn how to do this [Vite Package Setup](../../../../../customizing/development-flow/vite-package-setup.md) article.
+{% endhint %}
+
+In this example, you will take the native Tiptap open-source extension [Highlight](https://tiptap.dev/docs/editor/extensions/marks/highlight). Then register it with the rich text editor and add a toolbar button to invoke the Task List action.
+
+1. Install the Highlight extension from the npm registry.
+
+```
+npm install @tiptap/extension-highlight
+```
+
+2. Create the code to register the native Tiptap extensions in the rich text editor.
+
+```js
+import { UmbTiptapExtensionApiBase } from '@umbraco-cms/backoffice/tiptap';
+import { Highlight } from '@tiptap/extension-highlight';
+
+export default class UmbTiptapHighlightExtensionApi extends UmbTiptapExtensionApiBase {
+	getTiptapExtensions = () => [Highlight];
+}
+```
+
+3. Create the toolbar action to invoke the Highlight extension.
+
+```
+import { UmbTiptapToolbarElementApiBase } from '@umbraco-cms/backoffice/tiptap';
+import type { Editor } from '@umbraco-cms/backoffice/external/tiptap';
+
+export default class UmbTiptapToolbarHighlightExtensionApi extends UmbTiptapToolbarElementApiBase {
+    override execute(editor?: Editor) {
+        editor?.chain().focus().toggleHighlight().run();
+    }
+}
+```
+
+Once you have the above code in place, they can be referenced in the [package manifest](../../../../../extending/property-editors/package-manifest.md) file.
+
+{% code title="App_Plugins/MyTiptapExtension/umbraco-package.json" lineNumbers="true" %}
+```json
+{
+    "name": "My Tiptap Extension",
+    "version": "1.0.0",
+    "extensions": [
+        {
+            "type": "tiptapExtension",
+            "alias": "My.Tiptap.Highlight",
+            "name": "My Highlight Tiptap Extension",
+            "api": "/App_Plugins/MyTiptapExtension/highlight.tiptap-api.js",
+            "meta": {
+                "icon": "icon-thumbnail-list",
+                "label": "Highlight",
+                "group": "#tiptap_extGroup_formatting"
+            }
+        },
+        {
+            "type": "tiptapToolbarExtension",
+            "kind": "button",
+            "alias": "My.Tiptap.Toolbar.TaskList",
+            "name": "My Highlight Tiptap Toolbar Extension",
+            "api": "/App_Plugins/MyTiptapExtension/highlight.tiptap-toolbar-api.js",
+            "meta": {
+                "alias": "highlight",
+                "icon": "icon-brush",
+                "label": "Highlight"
+            }
+        }
+    ]
+}
+```
+{% endcode %}
+
+Upon restarting Umbraco, the new extension and toolbar action will be available in the Tiptap Data Type configuration settings.