Tiptap Markdown Editor

Portable module that upgrades a standard <textarea> into a Tiptap + Markdown editor for host applications.

Disclaimer

This project is not affiliated with the official Tiptap project.

It is a lightweight wrapper that adds Markdown support and a portable toolbar for enhancing textarea fields.

Production Install

npm

npm install tiptap-markdown-textarea

CDN (version-pinned)

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/tiptap-markdown-textarea.css">
<script type="module">
  import { init } from 'https://cdn.jsdelivr.net/npm/[email protected]/dist/tiptap-markdown-textarea.js';
  await init('message-editor');
</script>

Quick Start (Production)

<form method="post" action="/save" id="message-form">
  <textarea id="message-editor" name="message" data-tiptap-markdown></textarea>
  <button type="submit">Save</button>
</form>

<link rel="stylesheet" href="/dist/tiptap-markdown-textarea.css">
<script type="module">
  import { init } from '/dist/tiptap-markdown-textarea.js';

  try {
    await init('message-editor', {
      height: 360,
      counter: true,
    });
  } catch (error) {
    console.error('Editor initialization failed.', error);
  }
</script>

Configuration

API

• init(textareaId, options = {}) -> returns controller
• initAll(selector = 'textarea[data-tiptap-markdown][id]', options = {}) -> returns controller array
• destroy(textareaId) -> destroys one mounted editor

Controller Methods

• getMarkdown()
• setMarkdown(markdown)
• focus()
• isEmpty()
• setDisabled(boolean)
• setReadonly(boolean)
• destroy()

Callbacks

• onReady(controller)
• onChange(markdown, controller)
• onFocus(controller)
• onBlur(controller)
• onError(error, context)

Common Options

Core:

• height
• placeholder
• disabled
• readonly
• toolbarCommands
• messages
• htmlAttributes

UX/perf:

• counter (true or { mode: 'words' | 'characters' | 'both' })
• shortcuts
• debounceMs (default 120)
• syntaxHighlighting (true by default)
• syntaxHighlighting: { enabled?: boolean, languages?: string[] }
• default highlight languages: json, js, ts, bash, markdown

Safety limits:

• limits.maxLinkUrlLength
• limits.maxImageUrlLength
• limits.maxImageAltLength
• limits.maxTableRows
• limits.maxTableCols

Styling:

• iconSet: 'text' | 'fontawesome'
• classes
• classes.toolbarButtonByAction

Error Handling Contract

init(...) and initAll(...) throw TiptapMarkdownEditorError when setup/config is invalid.

Error codes:

• E_INVALID_TEXTAREA_ID
• E_TEXTAREA_NOT_FOUND
• E_FORM_NOT_FOUND
• E_INVALID_SELECTOR
• E_INVALID_OPTION
• E_INIT_FAILED

Use try/catch around await init(...) / await initAll(...).

Migration and Upgrades

• Migration details: docs/MIGRATION.md
• Upgrade checklist: docs/UPGRADE.md

Legacy aliases remain in 1.x and are deprecated:

• initTiptapMarkdownEditor(...)
• initAllTiptapMarkdownEditors(...)

Removal is planned for 2.0.0.

Examples (Copy-Paste)

• NPM example: examples/npm/basic.html
• CDN example: examples/cdn/basic.html
• PHP form-post example: examples/index.php
• All examples index: examples/README.md

Troubleshooting

• E_TEXTAREA_NOT_FOUND: check id and script execution timing.
• E_FORM_NOT_FOUND: editor textarea must be inside a <form>.
• E_INVALID_SELECTOR: validate selector passed to initAll(...).
• Empty toolbar/icons: ensure CSS is loaded and custom class overrides are valid.
• URL rejected in dialogs: only http/https URLs are accepted.

Compatibility and Overrides

• Browser support and limitations: docs/BROWSER-SUPPORT.md
• CSS compatibility and overrides: docs/STYLING.md

Security

• Security policy: SECURITY.md

Performance

• Performance guide and budgets: docs/PERFORMANCE.md
• Benchmark command:

npm run bench:perf

Changelog

• CHANGELOG.md

Development

npm install
npm run build
npm test