README

A powerful, user-friendly Tiptap field for Kirby.

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 a content sanitizer that automatically removes formatting you don't want
🛼 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 fields
🔗 Improved link handling with a dialog that automatically picks the right KirbyTag ((link: ), (email: ), (file: )or (tel: )) and a paste handler that adds link tags to the selected text
🌈 Custom highlights via a regular expression config option, making it possible to e.g. highlight long words
📋 Abstracted JSON structure for easy content manipulation with features like offsetHeadings

Usage

Blueprints

Available buttons

tiptap:
  buttons:
    - headings:
        - 1
        - 2
        - 3
    - "|"
    - bold
    - italic
    - strike
    - code
    - codeBlock
    - "|"
    - link
    - image
    - "|"
    - bulletList
    - orderedList

Available options

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
  required: true
  placeholder: My placeholder
  default: My default content
  disabled: true
  help: My help
  maxlength: 10
  minlength: 10

Template

// Basic usage
echo $page->text()->tiptapText();

// With heading level offset
echo $page->text()->tiptapText([
  'offsetHeadings' => 1
]);

Roadmap

Coming soon

Image uploads
Custom buttons

Under consideration

Kirbytag button (fetch all Kirbytags except link, image and file?)
Table button
Replacement for Writer blocks (?)
Attachement/file button (with uploads)
Settings for links
- Upload location
- Link types
- Fields in dialog
"Remove formatting" button (?)
Snapshot Compare
Blocks replacement
Forced content structure
Real-time collaboration

Motivation

Put simply, I'm not happy with any of the existing options.

Textarea field

Being a purist myself, this has long been my favorite. This delightfully simple field comes with quite a few drawbacks, though. Among others:

Pressing formatting buttons only inserts characters. This can lead to My # heading or My - list.
No undo functionality for formatting
No configurable headlines
No syntax highlighting, making it hard for my clients to understand.
Links don't insert (email: ), (file: ), (tel: ) tags, only (link: )

Writer field

The Writer field is what Kirby uses for the default text blocks. That's where it shines but in my experience it's not a replacement for a standalone content field.

Experimental permalinksToUrls() method pretty much unavoidable
No size option
No HTML allowed
No highlighting for KirbyTags
Not possible to add images/videos/…
Complex nodes/marks differentiation, UX for lists
Redundant email button
Massive issues with copying text containing gender stars (getkirby/kirby#3138)
Losing content

medienbaecker / kirby-tiptap

Maintainers

Details