@tiptap/core 3.6.6 → 3.7.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tiptap/core",
   "description": "headless rich text editor",
-  "version": "3.6.6",
+  "version": "3.7.0",
   "homepage": "https://tiptap.dev",
   "keywords": [
     "tiptap",
@@ -52,10 +52,10 @@
     "jsx-dev-runtime"
   ],
   "devDependencies": {
-    "@tiptap/pm": "^3.6.6"
+    "@tiptap/pm": "^3.7.0"
   },
   "peerDependencies": {
-    "@tiptap/pm": "^3.6.6"
+    "@tiptap/pm": "^3.7.0"
   },
   "repository": {
     "type": "git",

package/src/Extendable.ts

@@ -12,9 +12,16 @@ import type {
   EditorEvents,
   Extensions,
   GlobalAttributes,
+  JSONContent,
   KeyboardShortcutCommand,
+  MarkdownParseHelpers,
+  MarkdownParseResult,
+  MarkdownRendererHelpers,
+  MarkdownToken,
+  MarkdownTokenizer,
   ParentConfig,
   RawCommands,
+  RenderContext,
 } from './types.js'
 import { callOrReturn } from './utilities/callOrReturn.js'
 import { mergeDeep } from './utilities/mergeDeep.js'
@@ -224,6 +231,43 @@ export interface ExtendableConfig<
     parent: ParentConfig<Config>['addExtensions']
   }) => Extensions
 
+  /**
+   * The markdown token name
+   *
+   * This is the name of the token that this extension uses to parse and render markdown and comes from the Marked Lexer.
+   *
+   * @see https://github.com/markedjs/marked/blob/master/src/Tokens.ts
+   *
+   */
+  markdownTokenName?: string
+
+  /**
+   * The parse function used by the markdown parser to convert markdown tokens to ProseMirror nodes.
+   */
+  parseMarkdown?: (token: MarkdownToken, helpers: MarkdownParseHelpers) => MarkdownParseResult
+
+  /**
+   * The serializer function used by the markdown serializer to convert ProseMirror nodes to markdown tokens.
+   */
+  renderMarkdown?: (node: JSONContent, helpers: MarkdownRendererHelpers, ctx: RenderContext) => string
+
+  /**
+   * The markdown tokenizer responsible for turning a markdown string into tokens
+   *
+   * Custom tokenizers are only needed when you want to parse non-standard markdown token.
+   */
+  markdownTokenizer?: MarkdownTokenizer
+
+  /**
+   * Optional markdown options for indentation
+   */
+  markdownOptions?: {
+    /**
+     * Defines if this markdown element should indent it's child elements
+     */
+    indentsContent?: boolean
+  }
+
   /**
    * This function extends the schema of the node.
    * @example

package/src/ExtensionManager.ts

@@ -29,12 +29,21 @@ export class ExtensionManager {
 
   schema: Schema
 
+  /**
+   * A flattened and sorted array of all extensions
+   */
   extensions: Extensions
 
+  /**
+   * A non-flattened array of base extensions (no sub-extensions)
+   */
+  baseExtensions: Extensions
+
   splittableMarks: string[] = []
 
   constructor(extensions: Extensions, editor: Editor) {
     this.editor = editor
+    this.baseExtensions = extensions
     this.extensions = resolveExtensions(extensions)
     this.schema = getSchemaByResolvedExtensions(this.extensions, editor)
     this.setupExtensions()

package/src/commands/insertContent.ts

@@ -2,6 +2,20 @@ import type { Fragment, Node as ProseMirrorNode, ParseOptions } from '@tiptap/pm
 
 import type { Content, RawCommands } from '../types.js'
 
+export interface InsertContentOptions {
+  /**
+   * Options for parsing the content.
+   */
+  parseOptions?: ParseOptions
+
+  /**
+   * Whether to update the selection after inserting the content.
+   */
+  updateSelection?: boolean
+  applyInputRules?: boolean
+  applyPasteRules?: boolean
+}
+
 declare module '@tiptap/core' {
   interface Commands<ReturnType> {
     insertContent: {
@@ -19,19 +33,7 @@ declare module '@tiptap/core' {
         /**
          * Optional options
          */
-        options?: {
-          /**
-           * Options for parsing the content.
-           */
-          parseOptions?: ParseOptions
-
-          /**
-           * Whether to update the selection after inserting the content.
-           */
-          updateSelection?: boolean
-          applyInputRules?: boolean
-          applyPasteRules?: boolean
-        },
+        options?: InsertContentOptions,
       ) => ReturnType
     }
   }

package/src/commands/insertContentAt.ts

@@ -5,6 +5,33 @@ import { createNodeFromContent } from '../helpers/createNodeFromContent.js'
 import { selectionToInsertionEnd } from '../helpers/selectionToInsertionEnd.js'
 import type { Content, Range, RawCommands } from '../types.js'
 
+export interface InsertContentAtOptions {
+  /**
+   * Options for parsing the content.
+   */
+  parseOptions?: ParseOptions
+
+  /**
+   * Whether to update the selection after inserting the content.
+   */
+  updateSelection?: boolean
+
+  /**
+   * Whether to apply input rules after inserting the content.
+   */
+  applyInputRules?: boolean
+
+  /**
+   * Whether to apply paste rules after inserting the content.
+   */
+  applyPasteRules?: boolean
+
+  /**
+   * Whether to throw an error if the content is invalid.
+   */
+  errorOnInvalidContent?: boolean
+}
+
 declare module '@tiptap/core' {
   interface Commands<ReturnType> {
     insertContentAt: {
@@ -26,32 +53,7 @@ declare module '@tiptap/core' {
         /**
          * Optional options
          */
-        options?: {
-          /**
-           * Options for parsing the content.
-           */
-          parseOptions?: ParseOptions
-
-          /**
-           * Whether to update the selection after inserting the content.
-           */
-          updateSelection?: boolean
-
-          /**
-           * Whether to apply input rules after inserting the content.
-           */
-          applyInputRules?: boolean
-
-          /**
-           * Whether to apply paste rules after inserting the content.
-           */
-          applyPasteRules?: boolean
-
-          /**
-           * Whether to throw an error if the content is invalid.
-           */
-          errorOnInvalidContent?: boolean
-        },
+        options?: InsertContentAtOptions,
       ) => ReturnType
     }
   }

package/src/commands/setContent.ts

@@ -3,6 +3,25 @@ import type { Fragment, Node as ProseMirrorNode, ParseOptions } from '@tiptap/pm
 import { createDocument } from '../helpers/createDocument.js'
 import type { Content, RawCommands } from '../types.js'
 
+export interface SetContentOptions {
+  /**
+   * Options for parsing the content.
+   * @default {}
+   */
+  parseOptions?: ParseOptions
+
+  /**
+   * Whether to throw an error if the content is invalid.
+   */
+  errorOnInvalidContent?: boolean
+
+  /**
+   * Whether to emit an update event.
+   * @default true
+   */
+  emitUpdate?: boolean
+}
+
 declare module '@tiptap/core' {
   interface Commands<ReturnType> {
     setContent: {
@@ -22,24 +41,7 @@ declare module '@tiptap/core' {
         /**
          * Options for `setContent`.
          */
-        options?: {
-          /**
-           * Options for parsing the content.
-           * @default {}
-           */
-          parseOptions?: ParseOptions
-
-          /**
-           * Whether to throw an error if the content is invalid.
-           */
-          errorOnInvalidContent?: boolean
-
-          /**
-           * Whether to emit an update event.
-           * @default true
-           */
-          emitUpdate?: boolean
-        },
+        options?: SetContentOptions,
       ) => ReturnType
     }
   }

package/src/index.ts

@@ -1,5 +1,8 @@
 export * from './CommandManager.js'
+export type * from './commands/index.js'
+export * as commands from './commands/index.js'
 export * from './Editor.js'
+export * from './Extendable.js'
 export * from './Extension.js'
 export * as extensions from './extensions/index.js'
 export * from './helpers/index.js'

package/src/pasteRules/nodePasteRule.ts

@@ -8,7 +8,7 @@ import { callOrReturn } from '../utilities/index.js'
 /**
  * Build an paste rule that adds a node when the
  * matched text is pasted into it.
- * @see https://tiptap.dev/docs/editor/extensions/custom-extensions/extend-existing#paste-rules
+ * @see https://tiptap.dev/docs/editor/api/paste-rules
  */
 export function nodePasteRule(config: {
   find: PasteRuleFinder

package/src/types.ts

@@ -755,3 +755,159 @@ export type ExtendedRegExpMatchArray = RegExpMatchArray & {
 }
 
 export type Dispatch = ((args?: any) => any) | undefined
+
+/** Markdown related types */
+
+// Shared markdown-related types for the MarkdownManager and extensions.
+export type MarkdownToken = {
+  type?: string
+  raw?: string
+  text?: string
+  tokens?: MarkdownToken[]
+  depth?: number
+  items?: MarkdownToken[]
+  [key: string]: any
+}
+
+export type MarkdownHelpers = {
+  // When used during parsing these helpers return JSON-like node objects
+  // (not ProseMirror Node instances). Use `any` to represent that shape.
+  parseInline: (tokens: MarkdownToken[]) => any[]
+  /**
+   * Render children. The second argument may be a legacy separator string
+   * or a RenderContext (preferred).
+   */
+  renderChildren: (node: Node[] | Node, ctxOrSeparator?: RenderContext | string) => string
+  text: (token: MarkdownToken) => any
+}
+
+/**
+ * Helpers specifically for parsing markdown tokens into Tiptap JSON.
+ * These are provided to extension parse handlers.
+ */
+export type MarkdownParseHelpers = {
+  /** Parse an array of inline tokens into text nodes with marks */
+  parseInline: (tokens: MarkdownToken[]) => JSONContent[]
+  /** Parse an array of block-level tokens */
+  parseChildren: (tokens: MarkdownToken[]) => JSONContent[]
+  /** Create a text node with optional marks */
+  createTextNode: (text: string, marks?: Array<{ type: string; attrs?: any }>) => JSONContent
+  /** Create any node type with attributes and content */
+  createNode: (type: string, attrs?: any, content?: JSONContent[]) => JSONContent
+  /** Apply a mark to content (used for inline marks like bold, italic) */
+  applyMark: (
+    markType: string,
+    content: JSONContent[],
+    attrs?: any,
+  ) => { mark: string; content: JSONContent[]; attrs?: any }
+}
+
+/**
+ * Full runtime helpers object provided by MarkdownManager to handlers.
+ * This includes the small author-facing helpers plus internal helpers
+ * that can be useful for advanced handlers.
+ */
+export type FullMarkdownHelpers = MarkdownHelpers & {
+  // parseChildren returns JSON-like nodes when invoked during parsing.
+  parseChildren: (tokens: MarkdownToken[]) => any[]
+  getExtension: (name: string) => any
+  // createNode returns a JSON-like node during parsing; render-time helpers
+  // may instead work with real ProseMirror Node instances.
+  createNode: (type: string, attrs?: any, content?: any[]) => any
+  /** Current render context when calling renderers; undefined during parse. */
+  currentContext?: RenderContext
+  /** Indent a multi-line string according to the provided RenderContext. */
+  indent: (text: string, ctx?: RenderContext) => string
+  /** Return the indent string for a given level (e.g. '  ' or '\t'). */
+  getIndentString: (level?: number) => string
+}
+
+export default MarkdownHelpers
+
+/**
+ * Return shape for parser-level `parse` handlers.
+ * - a single JSON-like node
+ * - an array of JSON-like nodes
+ * - or a `{ mark: string, content: JSONLike[] }` shape to apply a mark
+ */
+export type MarkdownParseResult = JSONContent | JSONContent[] | { mark: string; content: JSONContent[]; attrs?: any }
+
+export type RenderContext = {
+  index: number
+  level: number
+  meta?: Record<string, any>
+  parentType?: string | null
+}
+
+/** Extension contract for markdown parsing/serialization. */
+export interface MarkdownExtensionSpec {
+  /** Token name used for parsing (e.g., 'codespan', 'code', 'strong') */
+  tokenName?: string
+  /** Node/mark name used for rendering (typically the extension name) */
+  nodeName?: string
+  parseMarkdown?: (token: MarkdownToken, helpers: MarkdownParseHelpers) => MarkdownParseResult
+  renderMarkdown?: (node: any, helpers: MarkdownRendererHelpers, ctx: RenderContext) => string
+  isIndenting?: boolean
+  /** Custom tokenizer for marked.js to handle non-standard markdown syntax */
+  tokenizer?: MarkdownTokenizer
+}
+
+/**
+ * Configuration object passed to custom marked.js tokenizers
+ */
+export type MarkdownLexerConfiguration = {
+  /**
+   * Can be used to transform source text into inline tokens - useful while tokenizing child tokens.
+   * @param src
+   * @returns Array of inline tokens
+   */
+  inlineTokens: (src: string) => MarkdownToken[]
+
+  /**
+   * Can be used to transform source text into block-level tokens - useful while tokenizing child tokens.
+   * @param src
+   * @returns Array of block-level tokens
+   */
+  blockTokens: (src: string) => MarkdownToken[]
+}
+
+/** Custom tokenizer function for marked.js extensions */
+export type MarkdownTokenizer = {
+  /** Token name this tokenizer creates */
+  name: string
+  /** Priority level for tokenizer ordering (higher = earlier) */
+  level?: 'block' | 'inline'
+  /** A string to look for or a function that returns the start index of the token in the source string */
+  start?: string | ((src: string) => number)
+  /** Function that attempts to parse custom syntax from start of text */
+  tokenize: (
+    src: string,
+    tokens: MarkdownToken[],
+    lexer: MarkdownLexerConfiguration,
+  ) => MarkdownToken | undefined | void
+}
+
+export type MarkdownRendererHelpers = {
+  /**
+   * Render children nodes to a markdown string, optionally separated by a string.
+   * @param nodes The node or array of nodes to render
+   * @param separator An optional separator string (legacy) or RenderContext
+   * @returns The rendered markdown string
+   */
+  renderChildren: (nodes: JSONContent | JSONContent[], separator?: string) => string
+
+  /**
+   * Render a text token to a markdown string
+   * @param prefix The prefix to add before the content
+   * @param content The content to wrap
+   * @returns The wrapped content
+   */
+  wrapInBlock: (prefix: string, content: string) => string
+
+  /**
+   * Indent a markdown string according to the provided RenderContext
+   * @param content The content to indent
+   * @returns The indented content
+   */
+  indent: (content: string) => string
+}

package/src/utilities/index.ts

@@ -15,6 +15,8 @@ export * from './isNumber.js'
 export * from './isPlainObject.js'
 export * from './isRegExp.js'
 export * from './isString.js'
+export * from './markdown/index.js'
+export * as markdown from './markdown/index.js'
 export * from './mergeAttributes.js'
 export * from './mergeDeep.js'
 export * from './minMax.js'

package/src/utilities/markdown/attributeUtils.ts

@@ -0,0 +1,130 @@
+/**
+ * @fileoverview Utility functions for parsing and serializing markdown attributes.
+ *
+ * These utilities handle the common patterns for parsing attribute strings
+ * in various markdown syntaxes like Pandoc attributes.
+ */
+
+/**
+ * Parses a Pandoc-style attribute string into an object.
+ *
+ * Supports the following patterns:
+ * - Classes: `.className` → `{ class: 'className' }`
+ * - IDs: `#myId` → `{ id: 'myId' }`
+ * - Key-value pairs: `key="value"` → `{ key: 'value' }`
+ * - Boolean attributes: `disabled` → `{ disabled: true }`
+ *
+ * @param attrString - The attribute string to parse
+ * @returns Parsed attributes object
+ *
+ * @example
+ * ```ts
+ * parseAttributes('.btn #submit disabled type="button"')
+ * // → { class: 'btn', id: 'submit', disabled: true, type: 'button' }
+ * ```
+ */
+export function parseAttributes(attrString: string): Record<string, any> {
+  if (!attrString?.trim()) {
+    return {}
+  }
+
+  const attributes: Record<string, any> = {}
+
+  // First, extract and remove quoted strings to avoid parsing content inside them
+  const quotedStrings: string[] = []
+  const tempString = attrString.replace(/["']([^"']*)["']/g, match => {
+    quotedStrings.push(match)
+    return `__QUOTED_${quotedStrings.length - 1}__`
+  })
+
+  // Parse classes (.className) - only outside of quoted strings
+  const classMatches = tempString.match(/(?:^|\s)\.([a-zA-Z][\w-]*)/g)
+  if (classMatches) {
+    const classes = classMatches.map(match => match.trim().slice(1)) // Remove the dot
+    attributes.class = classes.join(' ')
+  }
+
+  // Parse IDs (#myId) - only outside of quoted strings
+  const idMatch = tempString.match(/(?:^|\s)#([a-zA-Z][\w-]*)/)
+  if (idMatch) {
+    attributes.id = idMatch[1]
+  }
+
+  // Parse key-value pairs (key="value" or key='value') - restore quoted strings
+  const kvRegex = /([a-zA-Z][\w-]*)\s*=\s*(__QUOTED_\d+__)/g
+  const kvMatches = Array.from(tempString.matchAll(kvRegex))
+  kvMatches.forEach(([, key, quotedRef]) => {
+    const quotedIndex = parseInt(quotedRef.match(/__QUOTED_(\d+)__/)?.[1] || '0', 10)
+    const quotedValue = quotedStrings[quotedIndex]
+    if (quotedValue) {
+      // Remove the outer quotes
+      attributes[key] = quotedValue.slice(1, -1)
+    }
+  })
+
+  // Parse boolean attributes (standalone words that aren't classes/IDs)
+  const cleanString = tempString
+    .replace(/(?:^|\s)\.([a-zA-Z][\w-]*)/g, '') // Remove classes
+    .replace(/(?:^|\s)#([a-zA-Z][\w-]*)/g, '') // Remove IDs
+    .replace(/([a-zA-Z][\w-]*)\s*=\s*__QUOTED_\d+__/g, '') // Remove key-value pairs
+    .trim()
+
+  if (cleanString) {
+    const booleanAttrs = cleanString.split(/\s+/).filter(Boolean)
+    booleanAttrs.forEach(attr => {
+      if (attr.match(/^[a-zA-Z][\w-]*$/)) {
+        attributes[attr] = true
+      }
+    })
+  }
+
+  return attributes
+}
+
+/**
+ * Serializes an attributes object back to a Pandoc-style attribute string.
+ *
+ * @param attributes - The attributes object to serialize
+ * @returns Serialized attribute string
+ *
+ * @example
+ * ```ts
+ * serializeAttributes({ class: 'btn primary', id: 'submit', disabled: true, type: 'button' })
+ * // → '.btn.primary #submit disabled type="button"'
+ * ```
+ */
+export function serializeAttributes(attributes: Record<string, any>): string {
+  if (!attributes || Object.keys(attributes).length === 0) {
+    return ''
+  }
+
+  const parts: string[] = []
+
+  // Handle classes
+  if (attributes.class) {
+    const classes = String(attributes.class).split(/\s+/).filter(Boolean)
+    classes.forEach(cls => parts.push(`.${cls}`))
+  }
+
+  // Handle ID
+  if (attributes.id) {
+    parts.push(`#${attributes.id}`)
+  }
+
+  // Handle other attributes
+  Object.entries(attributes).forEach(([key, value]) => {
+    if (key === 'class' || key === 'id') {
+      return // Already handled
+    }
+
+    if (value === true) {
+      // Boolean attribute
+      parts.push(key)
+    } else if (value !== false && value != null) {
+      // Key-value attribute
+      parts.push(`${key}="${String(value)}"`)
+    }
+  })
+
+  return parts.join(' ')
+}