Relevant source files

The following files were used as context for generating this wiki page: - [src/components/editor/DocumentEditor.tsx](https://github.com/ThinkEx-OSS/thinkex/blob/main/src/components/editor/DocumentEditor.tsx) - [src/lib/utils/format-workspace-context.ts](https://github.com/ThinkEx-OSS/thinkex/blob/main/src/lib/utils/format-workspace-context.ts) - [src/components/tiptap-ui/mark-button/use-mark.ts](https://github.com/ThinkEx-OSS/thinkex/blob/main/src/components/tiptap-ui/mark-button/use-mark.ts) - [src/components/assistant-ui/markdown-text.tsx](https://github.com/ThinkEx-OSS/thinkex/blob/main/src/components/assistant-ui/markdown-text.tsx) - [src/lib/utils/markdown-extractor.ts](https://github.com/ThinkEx-OSS/thinkex/blob/main/src/lib/utils/markdown-extractor.ts) - [src/lib/exportToGoogleDocs.ts](https://github.com/ThinkEx-OSS/thinkex/blob/main/src/lib/exportToGoogleDocs.ts) - [package.json](https://github.com/ThinkEx-OSS/thinkex/blob/main/package.json)

# Rich Text Editing (Tiptap) Rich text editing in ThinkEx is powered by the [Tiptap](https://tiptap.dev/) 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. ```mermaid graph TD Editor[DocumentEditor] --> Extensions[Tiptap Extensions] Editor --> Toolbar[Custom Toolbar] Editor --> BubbleMenu[Ask AI Bubble Menu] Editor --> Content[EditorContent] Extensions --> StarterKit[StarterKit] Extensions --> Math[Mathematics/KaTeX] Extensions --> Tables[TableKit] Extensions --> MD[Markdown] Toolbar --> Blocks[Blocks Dropdown] Toolbar --> Marks[Inline Mark Buttons] Toolbar --> Alignment[Alignment Controls] ``` 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`. ```mermaid sequenceDiagram participant User participant Editor as Tiptap Editor participant Menu as AskAiBubbleMenu participant Store as UI Store User->>Editor: Selects Text Editor->>Menu: Trigger shouldShow() Menu->>User: Display "Ask AI" Button User->>Menu: Click "Ask AI" Menu->>Store: addReplySelection({text, title}) Menu->>User: Toast "Added to context" ``` 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 | | :--- | :--- | | `

` - `

` | `#` to `######` headers | | `` / `` | `**text**` | | `
` | `> text` | | `
` | ` ```language \n code \n ``` ` | | `` / `` | `- 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: 1. **Preprocessing**: LaTeX math is replaced with Unicode equivalents using `unicodeit`. 2. **Authentication**: Obtains a Google OAuth access token with `drive.file` scope. 3. **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.