Rich Text Editing (Tiptap)
Relevant source files
The following files were used as context for generating this wiki page:
Rich text editing in ThinkEx is powered by the Tiptap framework, providing a headless, customizable editor environment. It serves as the primary interface for creating and modifying structured knowledge, such as documents, within a workspace. The system integrates standard word-processing features with domain-specific capabilities like LaTeX mathematics, task management, and AI-assisted content generation.
The editor is designed to be highly extensible, utilizing a suite of core and custom Tiptap extensions to handle various content types. It supports bi-directional conversion between JSON and Markdown, enabling seamless export to external platforms and facilitating AI processing of document content.
Architecture and Core Component
The central component is the DocumentEditor, which wraps the Tiptap useEditor hook and manages the editor's lifecycle, state, and toolbar UI.
The DocumentEditor Component
The DocumentEditor acts as a controlled or uncontrolled component depending on the provided props. It initializes the editor with a comprehensive set of extensions and provides a custom toolbar for formatting.
The diagram shows the internal structure of the DocumentEditor component and its dependency on various Tiptap subsystems.
Sources: src/components/editor/DocumentEditor.tsx:162-230
Key Props and Configuration
The editor supports various configurations through the DocumentEditorProps interface:
| Prop | Type | Description |
|---|---|---|
content | JSONContent | string | Initial content in JSON or Markdown format. |
contentType | "json" | "markdown" | Specifies the format of the provided content. |
onUpdate | (update: DocumentEditorUpdate) => void | Callback triggered when content changes, returning JSON, text, and Markdown. |
embedded | boolean | Adjusts styles for use within other components (e.g., cards). |
autofocus | boolean | Whether to focus the editor on mount. |
Sources: src/components/editor/DocumentEditor.tsx:106-121
Extension System
ThinkEx utilizes a robust set of Tiptap extensions to provide specialized editing capabilities.
Standard and Formatting Extensions
- StarterKit: Includes basic nodes like paragraphs, headings, and bold/italic formatting.
- Typography: Enhances text with smart quotes and dashes.
- TextAlign: Supports left, center, right, and justified alignment for headings and paragraphs.
- TaskList & TaskItem: Enables interactive checklists with nesting support.
Sources: src/components/editor/DocumentEditor.tsx:555-578
Mathematics and KaTeX
The editor integrates Mathematics (based on KaTeX) to handle LaTeX formulas. It supports both inline math (using $) and block math (using $$).
- Formatting Rules: The system enforces specific rules for AI tools, such as escaping currency dollar signs as
\$to prevent accidental math parsing. - Diagrams: While the editor handles math, Mermaid diagrams are reserved for AI chat responses and are typically not included in editable document content.
Sources: src/lib/utils/format-workspace-context.ts:162-200, src/components/editor/DocumentEditor.tsx:590-595
Custom Nodes and Features
- CustomCodeBlock: A tailored extension for syntax-highlighted code blocks with tab indentation support.
- ImageUploadNode: Handles drag-and-drop or selection of images with size limits (defined by
MAX_FILE_SIZE). - TableKit: Provides table creation and management, including row/column addition and deletion.
Sources: src/components/editor/DocumentEditor.tsx:565-570, src/components/editor/DocumentEditor.tsx:600-613
AI Integration and Context Management
The editor is tightly integrated with the platform's AI capabilities through selection tracking and context formatting.
"Ask AI" Bubble Menu
When a user selects text within the editor, a BubbleMenu appears. This menu provides an "Ask AI" button that extracts the selected text and adds it to the AI assistant's context via the useUIStore.
This sequence illustrates the flow of adding editor content to the AI conversation context.
Sources: src/components/editor/DocumentEditor.tsx:476-515
Context Formatting
Document content is converted to a specific Markdown format for the AI assistant. The formatDocumentDetailsFull function ensures the AI receives raw Markdown content along with any associated source URLs.
Sources: src/lib/utils/format-workspace-context.ts:517-532
Markdown Extraction Logic
The markdown-extractor.ts utility facilitates converting HTML/DOM selections back into valid Markdown syntax. This is used for "multi-highlight" functionality where multiple disparate selections are combined into a single document.
| HTML Tag | Markdown Conversion |
|---|---|
<h1> - <h6> | # to ###### headers |
<strong> / <b> | **text** |
<blockquote> | > text |
<pre><code> | ```language \n code \n ``` |
<ul> / <li> | - item |
Sources: src/lib/utils/markdown-extractor.ts:14-87
Export and Interoperability
The editor system supports exporting content to external formats, most notably Google Docs.
Google Docs Export Workflow
The export process involves several steps to ensure formatting consistency:
- Preprocessing: LaTeX math is replaced with Unicode equivalents using
unicodeit. - Authentication: Obtains a Google OAuth access token with
drive.filescope. - Multipart Upload: Sends the content to the Google Drive API as
text/markdown, which Google Docs automatically imports as a structured document.
Sources: src/lib/exportToGoogleDocs.ts:8-50, src/lib/exportToGoogleDocs.ts:175-200
Implementation Details
Mark Management Hook
The useMark hook is a specialized utility for managing inline styles (marks) like bold, italic, and code. It tracks editor state to determine if a specific mark is active or if it can be toggled given the current selection (e.g., marks are often disabled on image selections).
Sources: src/components/tiptap-ui/mark-button/use-mark.ts:122-167
Persistence and Serialization
The editor maintains state using Tiptap's internal JSON structure but provides Markdown serialization via the Markdown extension. On every update, the DocumentEditor calculates the JSON, plain text, and Markdown representations to notify parent components.
Sources: src/components/editor/DocumentEditor.tsx:614-633
Rich text editing in ThinkEx provides a bridge between user-generated notes and AI-assisted knowledge management. By utilizing Tiptap's extensible architecture, the system maintains a high degree of control over content structure while providing a familiar, responsive interface for users. The inclusion of specialized math and AI tools ensures the editor meets the specific needs of a technical knowledge workspace.