medienbaecker / kirby-tiptap
Kirby Tiptap
Fund package maintenance!
medienbaecker
Installs: 74
Dependents: 0
Suggesters: 0
Security: 0
Stars: 28
Watchers: 2
Forks: 1
Open Issues: 2
Language:Vue
Type:kirby-plugin
Requires
- getkirby/composer-installer: ^1.1
- ueberdosis/tiptap-php: ^2.0
This package is auto-updated.
Last update: 2025-10-01 12:23:12 UTC
README
A powerful, user-friendly Tiptap field for Kirby.
Table of Contents
Features
- 🌏 Best of both worlds: Uses (and highlights) KirbyTags for images/links while providing WYSIWYG formatting
- 📦 Supports all standard Kirby field features like
required
,default
,placeholder
,counter
,disabled
,help
,size
,spellcheck
andminlength
/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, smartypants, automatic inline mode and more - ✨ Intuitive drag & drop support for pages and files with intelligent spacing
- 👀 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 - 🌈 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
<script>
,<marquee>
, or <blink>
tag directly - 📋 Abstracted JSON structure for easy content manipulation with features like
offsetHeadings
Installation
Composer
composer require medienbaecker/kirby-tiptap
Manual
- Download or clone this repository
- Place the folder in your
site/plugins
directory
Usage
Blueprints
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
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
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
// Basic usage echo $page->text()->tiptapText(); // With options echo $page->text()->tiptapText([ 'offsetHeadings' => 1, 'allowHtml' => true ]);
Configuration
// site/config/config.php return [ // Supports https://getkirby.com/docs/reference/system/options/smartypants 'smartypants' => true, // Custom highlights via regex (can be styled via panel CSS) 'medienbaecker.tiptap.highlights' => [ [ 'pattern' => '\\b[a-zA-ZäöüÄÖÜß\\w]{20,}\\b', 'class' => 'long-word', 'title' => 'Long word (20+ characters)' ] ], // 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
- 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, the following shortcut is also available:
- Link dialog:
Cmd+K
(Mac) /Ctrl+K
(Windows/Linux)
Custom buttons
The plugin supports custom buttons that can add any attributes to nodes. This allows you to create semantic markup or add styling classes. Configure them in your config.php
:
return [ 'medienbaecker.tiptap.buttons' => [ 'twoColumn' => [ 'icon' => 'columns', 'title' => 'Two Columns', 'nodes' => ['paragraph'], 'attributes' => [ 'class' => 'two-column' ] ] ] ];
Then use them in blueprints just like any other button:
tiptap: buttons: - bold - italic - "|" - twoColumn # Custom button
Add corresponding CSS to your frontend and panel.css
for styling:
.two-column { column-count: 2; column-gap: 2rem; }
Converting existing fields
To convert existing textarea
or markdown
fields to the JSON this field expects, you can use the built-in tiptap:convert
CLI command:
kirby tiptap:convert
kirby tiptap:convert --dry-run
kirby tiptap:convert --page blog
The command looks at the blueprint to collect the fields and converts their values to HTML using Kirby's markdown()
method before transforming it to Tiptap's JSON format using the same logic as the field itself. After running the command you can change the field type in your blueprints to tiptap
.
Ideas for future improvements
- Kirbytag button? (Fetch all Kirbytags except
link
,image
andfile
?) - Table button
- Snapshot Compare?
- Blocks replacement?
- Forced content structure?
- Real-time collaboration?