PHPackages medienbaecker/kirby-tiptap - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. medienbaecker/kirby-tiptap ActiveKirby-plugin medienbaecker/kirby-tiptap ========================== Kirby Tiptap 1.1.3(1mo ago)36517↓50%2[1 issues](https://github.com/medienbaecker/kirby-tiptap/issues)MITVue Since Feb 3Pushed 1mo ago1 watchersCompare [ Source](https://github.com/medienbaecker/kirby-tiptap)[ Packagist](https://packagist.org/packages/medienbaecker/kirby-tiptap)[ GitHub Sponsors](https://github.com/medienbaecker)[ RSS](/packages/medienbaecker-kirby-tiptap/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (10)Dependencies (4)Versions (59)Used By (0) Kirby Tiptap ============ [](#kirby-tiptap) A powerful, user-friendly [Tiptap](https://tiptap.dev) field for [Kirby](https://getkirby.com). [![Kirby Tiptap editor with formatting toolbar and example content demonstrating KirbyTags, special character visibility, and the tiptapText() method functionality.](https://private-user-images.githubusercontent.com/7975568/543994658-6891c6ea-1c2a-4237-9283-eb78ab6ec778.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NzQzOTk2ODQsIm5iZiI6MTc3NDM5OTM4NCwicGF0aCI6Ii83OTc1NTY4LzU0Mzk5NDY1OC02ODkxYzZlYS0xYzJhLTQyMzctOTI4My1lYjc4YWI2ZWM3NzgucG5nP1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDI2MDMyNSUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyNjAzMjVUMDA0MzA0WiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9NzNiYmRmNDU0MzA5NjZjMjg4NDM4MmExZGNkZjljNTIyMGRlOTljZTBhZDg3NDViMzBmNGRiYTJkZjBjYWNmNiZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QifQ.9FeQhtapM7pdmHwYP6IH5f37V3qu0p3fY1ItC-2Fl5A)](https://private-user-images.githubusercontent.com/7975568/543994658-6891c6ea-1c2a-4237-9283-eb78ab6ec778.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NzQzOTk2ODQsIm5iZiI6MTc3NDM5OTM4NCwicGF0aCI6Ii83OTc1NTY4LzU0Mzk5NDY1OC02ODkxYzZlYS0xYzJhLTQyMzctOTI4My1lYjc4YWI2ZWM3NzgucG5nP1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDI2MDMyNSUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyNjAzMjVUMDA0MzA0WiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9NzNiYmRmNDU0MzA5NjZjMjg4NDM4MmExZGNkZjljNTIyMGRlOTljZTBhZDg3NDViMzBmNGRiYTJkZjBjYWNmNiZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QifQ.9FeQhtapM7pdmHwYP6IH5f37V3qu0p3fY1ItC-2Fl5A) Table of Contents ----------------- [](#table-of-contents) - [Features](#features) - [Installation](#installation) - [Usage](#usage) - [Blueprints](#blueprints) - [Blocks field](#blocks-field) - [Frontend/templates](#frontendtemplates) - [Configuration](#configuration) - [Keyboard shortcuts](#keyboard-shortcuts) - [Custom buttons](#custom-buttons) - [Extension API](#extension-api) - [Customizing HTML output](#customizing-html-output) - [Converting existing fields](#converting-existing-fields) - [Ideas for future improvements](#ideas-for-future-improvements) Features -------- [](#features) - 🌏 **Best of both worlds:** Uses (and highlights) [KirbyTags](https://getkirby.com/docs/reference/plugins/extensions/kirbytags) for images/links while providing WYSIWYG formatting - πŸ“¦ **Supports all standard Kirby field features** like `required`, `default`, `placeholder`, `counter`, `disabled`, `help`, `size`, `spellcheck` and `minlength`/`maxlength` - πŸ€“ **Smart text handling** with intuitive soft hyphen `(-)` and non-breaking space `(_)` replacements, and visible special characters - πŸ”§ **Configurable buttons** with customizable heading levels and custom buttons that can add any attributes to nodes - πŸ›Ό **Inline mode** for paragraph-free content with buttons being disabled automatically - 🧠 **One method to rule them all** with `tiptapText()` handling [UUID resolution](https://getkirby.com/docs/reference/templates/field-methods/permalinks-to-urls), [smartypants](https://getkirby.com/docs/reference/system/options/smartypants), automatic [inline mode](https://getkirby.com/docs/reference/templates/helpers/kirbytextinline) and more - ✨ **Intuitive drag & drop support** for pages and files with intelligent spacing - πŸ“‹ **Smart paste** converts HTML links to KirbyTags automatically - πŸ‘€ **Custom field preview** showing formatted text in structure/object fields - πŸ”— **Improved link and file handling** with dialogs that allow custom fields, automatically pick the right KirbyTag (`(link: )`, `(email: )`, `(file: )` or `(tel: )`) and allow editing existing links/files by pre-filling dialogs - πŸ” **Cmd+Click navigation** on page/file references to jump directly to the linked page or file in the Panel - 🌈 **Custom highlights** via a regular expression config option, making it possible to e.g. highlight long words - πŸ”§ **Optional setting to allow HTML code** so you can paste your ⁠favourite ``, `⁠`, or ⁠`` tag directly - 🧩 **Extension API** for third-party plugins to add custom buttons, keyboard shortcuts, and full Tiptap extensions - πŸ“‹ **Abstracted JSON structure** for easy content manipulation with features like `offsetHeadings` Installation ------------ [](#installation) ### Composer [](#composer) ``` composer require medienbaecker/kirby-tiptap ``` ### Manual [](#manual) 1. Download or clone this repository 2. Place the folder in your `⁠site/plugins` directory Usage ----- [](#usage) ### Blueprints [](#blueprints) #### Available buttons [](#available-buttons) ``` tiptap: buttons: # Default buttons: - headings: - 1 - 2 - 3 - bold - italic - link - file - bulletList - orderedList - taskList # Additional buttons: - strike - code - codeBlock - blockquote - horizontalRule - removeFormatting # Divider: (as many as you want) - "|" ``` #### Available options [](#available-options) ``` fields: text: type: tiptap inline: true # remove block elements like paragraphs counter: false # disable character counter size: small # small, medium, large, huge or the default auto spellcheck: false # disable spellcheck pretty: true # pretty-print JSON in content file (incompatible with structure fields) links: # Set link types in the link dialog options: - page - url # Add fields to the link dialog fields: class: label: Classes type: checkboxes options: border: Border shadow: Shadow rounded: Rounded files: # Add custom fields to the file dialog fields: caption: label: Caption type: textarea uploads: true # Enable file uploads (default: false) # Or with options: # uploads: # accept: 'image/*' # Restrict file types # template: 'image' # Template for uploaded files # parent: 'media' # Upload destination required: true placeholder: My placeholder default: My default content disabled: true help: My help maxlength: 10 minlength: 10 ``` ### Blocks field [](#blocks-field) Add Tiptap to your block editor alongside other content blocks: ``` # In your page blueprint fields: content: type: blocks fieldsets: - heading - text - tiptap # Add the Tiptap block - image ``` ### Frontend/templates [](#frontendtemplates) ``` // Basic usage echo $page->text()->tiptapText(); // With options echo $page->text()->tiptapText([ 'offsetHeadings' => 1, 'allowHtml' => true ]); ``` ### Configuration [](#configuration) ``` // site/config/config.php return [ // Supports https://getkirby.com/docs/reference/system/options/smartypants 'smartypants' => true, // UUID usage for KirbyTags when dragging pages/files 'medienbaecker.tiptap.uuid' => [ 'pages' => false, // Use page IDs instead of page://uuid 'files' => true // Keep using file://uuid ] // Or disable UUIDs entirely: // 'medienbaecker.tiptap.uuid' => false ]; ``` ### Keyboard shortcuts [](#keyboard-shortcuts) - **Bold**: `Cmd+B` (Mac) / `Ctrl+B` (Windows/Linux) - **Italic**: `Cmd+I` (Mac) / `Ctrl+I` (Windows/Linux) - **Strike**: `Cmd+Shift+S` (Mac) / `Ctrl+Shift+S` (Windows/Linux) - **Code**: `Cmd+E` (Mac) / `Ctrl+E` (Windows/Linux) - **Heading 1**: `Cmd+Alt+1` (Mac) / `Ctrl+Alt+1` (Windows/Linux) - **Heading 2**: `Cmd+Alt+2` (Mac) / `Ctrl+Alt+2` (Windows/Linux) - **Heading 3**: `Cmd+Alt+3` (Mac) / `Ctrl+Alt+3` (Windows/Linux) - **Heading 4**: `Cmd+Alt+4` (Mac) / `Ctrl+Alt+4` (Windows/Linux) - **Heading 5**: `Cmd+Alt+5` (Mac) / `Ctrl+Alt+5` (Windows/Linux) - **Heading 6**: `Cmd+Alt+6` (Mac) / `Ctrl+Alt+6` (Windows/Linux) - **Blockquote**: `Cmd+Shift+B` (Mac) / `Ctrl+Shift+B` (Windows/Linux) - **Code block**: `Cmd+Alt+C` (Mac) / `Ctrl+Alt+C` (Windows/Linux) - **Bullet list**: `Cmd+Shift+8` (Mac) / `Ctrl+Shift+8` (Windows/Linux) - **Ordered list**: `Cmd+Shift+7` (Mac) / `Ctrl+Shift+7` (Windows/Linux) While the above shortcuts all come from [Tiptap's defaults](https://tiptap.dev/docs/editor/core-concepts/keyboard-shortcuts), the following shortcut is also available: - **Link dialog**: `Cmd+K` (Mac) / `Ctrl+K` (Windows/Linux) ### Extension API [](#extension-api) Third-party Kirby plugins can extend the tiptap editor with custom buttons, keyboard shortcuts, and full Tiptap extensions via a window global registry. See the `extension-examples/` folder for working examples. #### Setup [](#setup) Every extension plugin needs a minimal `index.php` and an `index.js`: ```