Kirby Tiptap (WIP)

A powerful, user-friendly Tiptap field for Kirby.

Table of Contents

• Features
• Installation
• Usage
  • Blueprints
  • Blocks field
  • Frontend/templates
  • Configuration
  • Keyboard shortcuts
  • Custom buttons
  • Converting existing fields
• Ideas for future improvements

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 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, 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

1. Download or clone this repository
2. 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 and file?)
• Table button
• Snapshot Compare?
• Blocks replacement?
• Forced content structure?
• Real-time collaboration?