Portable Text Editor

The Portable Text Editor (@portabletext/editor) is a headless, schema-driven block content editor designed for React. It is built around the Portable Text specification and follows a 'bring your own UI' philosophy: the editor manages the content state and editing logic, while you provide the visual implementation.

Key architectural components include:

• Schema: Defines the allowed styles, decorators, annotations, lists, block objects, and inline objects.
• Rendering: Controlled via node registrations and render props on the PortableTextEditable component.
• Containers: Allow complex structures (like callouts, code blocks, or tables) to host editable block content.
• Behavior API: An extensible system for defining how users interact with the content.
• Plugins: A modular system to extend editor functionality.
• @portabletext/toolbar: A companion package providing headless hooks for building custom toolbar interfaces.

The @portabletext/markdown package (and related conversion logic) supports a wide range of Markdown syntax to transform it into structured Portable Text. Supported features include:

• Text Formatting: Bold (**bold**), italic (_italic_), inline code (`code`), and strikethrough (~~strikethrough~~). The parser supports nested formatting (e.g., bold and italic combined).
• Links and Images:
  • Inline links: [text](url)
  • Reference-style links: [text][ref1] with definitions like [ref1]: url
  • Implicit references
  • Block images: ![alt](url)
  • Inline images: text ![alt](url) text
  • Autolinks: <https://example.com> and <mailto:email@example.com>
• Code Blocks: Fenced code blocks (with syntax highlighting support) and indented code blocks.
• Blockquotes: Single and nested blockquotes.
• Lists:
  • Unordered lists (- or *)
  • Ordered lists (1.)
  • Mixed lists (nesting ordered lists inside unordered lists and vice versa)
• Tables: Standard Markdown table syntax.
• Horizontal Rules: Separators using ---.
• Headings: All levels from # Heading 1 to ###### Heading 6.
• Other: Hard line breaks (\), HTML passthrough (e.g., <div> or <span>), and special character handling (&, <, >).

The @portabletext/markdown package (and related conversion logic) supports a wide range of Markdown syntax to transform it into structured Portable Text. Supported features include:

• Text Formatting: Bold (**), Italic (_), Inline Code (`), and Strikethrough (~~). The parser supports deep nesting (e.g., bold inside italic).
• Links and Images: Inline links, reference-style links, and both block and inline images.
• Code Blocks: Fenced code blocks (with syntax highlighting) and indented code blocks.
• Blockquotes: Single and nested blockquotes.
• Lists: Unordered lists, ordered lists, and mixed lists (ordered parents with unordered children or vice versa) with deep nesting.
• Tables: Standard Markdown tables.
• Horizontal Rules: Separators using ---.
• Headings: All levels from # (H1) to ###### (H6).
• Advanced Elements: Autolinks (URLs and mailto:), hard line breaks, and HTML passthrough (preserving raw HTML tags).

This comprehensive support ensures that the resulting Portable Text preserves both the visual structure and the semantic meaning of the original Markdown.

The basic example serves as a reference for implementing a full-featured Portable Text editor using the following patterns:

• Schema Definition: Using defineSchema to configure decorators, annotations, styles, lists, block objects (e.g., images), and inline objects (e.g., stock tickers).
• Node Registrations: Mounting specific node types using NodePlugin. This involves using registration functions such as:
  • defineTextBlock
  • defineBlockObject
  • defineInlineObject
  • defineDecorator
  • defineAnnotation
• List Management: Implementing list numbering via @portabletext/plugin-list-index.
• Toolbar Implementation: Building custom toolbars that toggle marks, styles, and lists by using the useEditor and useEditorSelector hooks, combined with selectors from @portabletext/editor/selectors.
• Value Monitoring: Reading and reacting to editor value changes using EventListenerPlugin to render live JSON previews.

Portable Text stores content as structured JSON data rather than HTML strings or Markdown. This approach treats content as a sequence of typed blocks, making it platform-agnostic and highly queryable.

Key Characteristics

• No rendering assumptions: The data doesn't assume a target format (like HTML). You can render the same JSON to React, HTML, PDF, or plain text.
• Structured Blocks: Content is organized into blocks (e.g., _type: 'block') which contain children (spans of text) and markDefs (definitions for inline annotations like links).
• Extensibility: You can define custom block types (e.g., callToAction, imageGallery) or custom inline annotations (e.g., stockTicker) without breaking existing renderers.
• Queryability: Because it is JSON, you can perform precise queries (e.g., "find all blocks containing a link to /docs") without fragile regex or HTML parsing.

[
  {
    "_type": "block",
    "style": "normal",
    "children": [
      {"_type": "span", "text": "Read the "},
      {
        "_type": "span",
        "text": "documentation",
        "marks": ["a1b2c3"]
      },
      {"_type": "span", "text": " for "},
      {
        "_type": "span",
        "text": "details",
        "marks": ["strong"]
      },
      {"_type": "span", "text": "."}
    ],
    "markDefs": [
      {
        "_key": "a1b2c3",
        "_type": "link",
        "href": "/docs"
      }
    ]
  }
]