How aguingand/tiptap-markdown works
Project type and purpose
• This is not a full-stack app but a standalone, open-source JavaScript/TypeScript library: “tiptap-markdown.”
• It provides a Markdown extension for the Tiptap rich-text editor (built on ProseMirror), offering bidirectional conversion between Markdown strings and ProseMirror document models.
File structure
• src/
• index.js – entry point that registers the Markdown extension with Tiptap
• extensions/ – custom Tiptap extension definitions (marks, nodes, clipboard handlers, tight-list handling)
• parse/MarkdownParser.js – implements parsing from Markdown text to ProseMirror AST
• serialize/MarkdownSerializer.js (+ state.js) – serializes ProseMirror AST back to Markdown
• util/ – helper functions for DOM manipulation, extension lookup, markdown tweaks, ProseMirror integration
• example/ – sample Vue app demonstrating usage (Vite config, components, data, custom extensions)
• __tests__/ – unit and snapshot tests validating parsing, serialization, utilities
• docs/ – migration guide and high-level notes
• CI configs: GitHub workflows for test and deploy
• package.json, babel.config.js, vite.config.js – build, development, and distribution settings
Main components
• Tiptap Editor (Vue/React/etc.)
• Markdown Extension (your library)
• Extension Core (index.js, configuration API)
• Parser Module (MarkdownParser)
• Serializer Module (MarkdownSerializer)
• Extension Definitions (marks, nodes, clipboard hooks)
• Utility Layer
• Underlying ProseMirror Core (Document Model, Schema)
• Data artifacts
• Input: raw Markdown text
• In-memory: ProseMirror JSON/Node representation
• Output: Markdown text
• Example Application (Vue + Vite) demonstrating integration
• External Services & CI
• GitHub Actions (test.yml, deploy.yml)
• npm registry (publish target)
Component interactions and data flows
• User invokes editor.commands.setContent('…') → Markdown Extension intercepts content → Parser converts Markdown → ProseMirror document
• User edits document in Tiptap UI → internal ProseMirror state mutates
• editor.storage.markdown.getMarkdown() → Serializer walks ProseMirror state → produces Markdown string
• Custom extensions (e.g., container.js, highlight.js) plug into Tiptap lifecycle and affect both parsing and serialization
• Example App fetches content from example/src/data, initializes Editor, renders UI components (Editor.vue, MenuBar.vue)
Architectural patterns and design principles
• Plugin architecture: each “extension” (mark, node, behavior) is self-contained and registered via index.js
• Separation of concerns: parsing, serialization, extension definition, and utilities live in distinct modules
• Configuration-driven: Markdown.configure({ … }) lets consumers toggle features (html, tightLists, linkify, etc.)
• Test-driven development: comprehensive unit and snapshot tests guarantee fidelity of round-trip conversions