# aguingand/tiptap-markdown architecture

> Architecture diagram of the GitHub repository aguingand/tiptap-markdown, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aguingand/tiptap-markdown
- Repository: https://github.com/aguingand/tiptap-markdown

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% External Systems
  TiptapEditor["Tiptap Editor UI"]:::external
  ProseMirrorCore["ProseMirror Core\n(Document Model, Schema)"]:::external

  %% Data Artifacts
  RawMD["Raw Markdown\n(text)"]:::data
  PMState["ProseMirror State\n(JSON/Node)"]:::data
  OutMD["Markdown Output\n(text)"]:::data

  %% Public API / Extension Layer
  subgraph "Public API / Extension Layer"
    direction TB
    ExtCore["Extension Core\n(index.js, Markdown.js)"]:::public
  end

  %% Core Parsing/Serialization Logic
  subgraph "Core Logic"
    direction TB
    Parser["MarkdownParser\n(src/parse/MarkdownParser.js)"]:::core
    Serializer["MarkdownSerializer\n(src/serialize/MarkdownSerializer.js)"]:::core
    StateMod["Serializer State\n(src/serialize/state.js)"]:::core
  end

  %% Extension Definitions
  subgraph "Extension Definitions"
    direction TB
    Eid["extensions/index.js"]:::public
    subgraph Marks
      direction TB
      Bold["bold.js"]:::public
      CodeMk["code.js"]:::public
      HtmlMk["html.js"]:::public
      Italic["italic.js"]:::public
      LinkMk["link.js"]:::public
      Strike["strike.js"]:::public
    end
    subgraph Nodes
      direction TB
      BQ["blockquote.js"]:::public
      BL["bullet-list.js"]:::public
      CB["code-block.js"]:::public
      HB["hard-break.js"]:::public
      HD["heading.js"]:::public
      HR["horizontal-rule.js"]:::public
      HTMLNode["html.js"]:::public
      Img["image.js"]:::public
      LI["list-item.js"]:::public
      OL["ordered-list.js"]:::public
      Para["paragraph.js"]:::public
      Table["table.js"]:::public
      TI["task-item.js"]:::public
      TL["task-list.js"]:::public
      TextNode["text.js"]:::public
    end
    subgraph "Tiptap Hooks"
      direction TB
      Clip["clipboard.js"]:::public
      Tight["tight-lists.js"]:::public
    end
  end

  %% Utility Layer
  subgraph "Utilities"
    direction TB
    DOM["dom.js"]:::util
    ExtLookup["extensions.js"]:::util
    MDUtil["markdown.js"]:::util
    PMUtil["prosemirror.js"]:::util
  end

  %% Example Application
  subgraph "Example App (Vue + Vite)"
    direction TB
    ExMain["main.js"]:::example
    ExApp["App.vue"]:::example
    ExEditor["Editor.vue"]:::example
    ExMenu["MenuBar.vue"]:::example
    ExDataMD["content.md"]:::example
    ExDataJS["large-content.js"]:::example
    ExExtCont["container.js"]:::example
    ExExtHigh["highlight.js"]:::example
  end

  %% CI & Publish
  subgraph "CI & Deployment"
    direction TB
    GHTest["test.yml"]:::service
    GHDeploy["deploy.yml"]:::service
    NpmReg["npm Registry"]:::service
  end

  %% Flows
  RawMD -->|setContent| ExtCore
  ExtCore -->|parse| Parser
  Parser --> PMState
  PMState -->|getMarkdown| Serializer
  Serializer --> OutMD
  Serializer --> StateMod
  ExtCore --> Eid
  Eid --> Marks
  Eid --> Nodes
  Eid --> Clip
  Eid --> Tight
  Eid --> ExtLookup
  Eid --> MDUtil
  ExEditor --> ExtCore
  ExMain --> ExApp
  ExApp --> ExEditor
  ExApp --> ExMenu
  ExApp --> ExDataMD
  GHTest -->|run tests| ExtCore
  GHTest --> Parser
  GHTest --> Serializer
  GHDeploy -->|publish| NpmReg

  %% External connections
  TiptapEditor -->|editor.commands| ExtCore
  ExtCore -->|integrates| ProseMirrorCore

  %% Click Events
  click ExtCore "https://github.com/aguingand/tiptap-markdown/blob/main/src/index.js"
  click ExtCore "https://github.com/aguingand/tiptap-markdown/blob/main/src/Markdown.js"
  click Parser "https://github.com/aguingand/tiptap-markdown/blob/main/src/parse/MarkdownParser.js"
  click Serializer "https://github.com/aguingand/tiptap-markdown/blob/main/src/serialize/MarkdownSerializer.js"
  click StateMod "https://github.com/aguingand/tiptap-markdown/blob/main/src/serialize/state.js"
  click Eid "https://github.com/aguingand/tiptap-markdown/blob/main/src/extensions/index.js"
  click Bold "https://github.com/aguingand/tiptap-markdown/blob/main/src/extensions/marks/bold.js"
  click CodeMk "https://github.com/aguingand/tiptap-markdown/blob/main/src/extensions/marks/code.js"
  click HtmlMk "https://github.com/aguingand/tiptap-markdown/blob/main/src/extensions/marks/html.js"
  click Italic "https://github.com/aguingand/tiptap-markdown/blob/main/src/extensions/marks/italic.js"
  click LinkMk "https://github.com/aguingand/tiptap-markdown/blob/main/src/extensions/marks/link.js"
  click Strike "https://github.com/aguingand/tiptap-markdown/blob/main/src/extensions/marks/strike.js"
  click BQ "https://github.com/aguingand/tiptap-markdown/blob/main/src/extensions/nodes/blockquote.js"
  click BL "https://github.com/aguingand/tiptap-markdown/blob/main/src/extensions/nodes/bullet-list.js"
  click CB "https://github.com/aguingand/tiptap-markdown/blob/main/src/extensions/nodes/code-block.js"
  click HB "https://github.com/aguingand/tiptap-markdown/blob/main/src/extensions/nodes/hard-break.js"
  click HD "https://github.com/aguingand/tiptap-markdown/blob/main/src/extensions/nodes/heading.js"
  click HR "https://github.com/aguingand/tiptap-markdown/blob/main/src/extensions/nodes/horizontal-rule.js"
  click HTMLNode "https://github.com/aguingand/tiptap-markdown/blob/main/src/extensions/nodes/html.js"
  click Img "https://github.com/aguingand/tiptap-markdown/blob/main/src/extensions/nodes/image.js"
  click LI "https://github.com/aguingand/tiptap-markdown/blob/main/src/extensions/nodes/list-item.js"
  click OL "https://github.com/aguingand/tiptap-markdown/blob/main/src/extensions/nodes/ordered-list.js"
  click Para "https://github.com/aguingand/tiptap-markdown/blob/main/src/extensions/nodes/paragraph.js"
  click Table "https://github.com/aguingand/tiptap-markdown/blob/main/src/extensions/nodes/table.js"
  click TI "https://github.com/aguingand/tiptap-markdown/blob/main/src/extensions/nodes/task-item.js"
  click TL "https://github.com/aguingand/tiptap-markdown/blob/main/src/extensions/nodes/task-list.js"
  click TextNode "https://github.com/aguingand/tiptap-markdown/blob/main/src/extensions/nodes/text.js"
  click Clip "https://github.com/aguingand/tiptap-markdown/blob/main/src/extensions/tiptap/clipboard.js"
  click Tight "https://github.com/aguingand/tiptap-markdown/blob/main/src/extensions/tiptap/tight-lists.js"
  click DOM "https://github.com/aguingand/tiptap-markdown/blob/main/src/util/dom.js"
  click ExtLookup "https://github.com/aguingand/tiptap-markdown/blob/main/src/util/extensions.js"
  click MDUtil "https://github.com/aguingand/tiptap-markdown/blob/main/src/util/markdown.js"
  click PMUtil "https://github.com/aguingand/tiptap-markdown/blob/main/src/util/prosemirror.js"
  click ExMain "https://github.com/aguingand/tiptap-markdown/blob/main/example/src/main.js"
  click ExApp "https://github.com/aguingand/tiptap-markdown/blob/main/example/src/App.vue"
  click ExEditor "https://github.com/aguingand/tiptap-markdown/blob/main/example/src/components/Editor.vue"
  click ExMenu "https://github.com/aguingand/tiptap-markdown/blob/main/example/src/components/MenuBar.vue"
  click ExDataMD "https://github.com/aguingand/tiptap-markdown/blob/main/example/src/data/content.md"
  click ExDataJS "https://github.com/aguingand/tiptap-markdown/blob/main/example/src/data/large-content.js"
  click ExExtCont "https://github.com/aguingand/tiptap-markdown/blob/main/example/src/extensions/container.js"
  click ExExtHigh "https://github.com/aguingand/tiptap-markdown/blob/main/example/src/extensions/highlight.js"

  %% Styles
  classDef public fill:#e0f7fa,stroke:#006064,color:#006064
  classDef core fill:#e8f5e9,stroke:#2e7d32,color:#2e7d32
  classDef util fill:#eceff1,stroke:#37474f,color:#37474f
  classDef example fill:#fff3e0,stroke:#ef6c00,color:#e65100
  classDef external fill:#f3e5f5,stroke:#6a1b9a,color:#4a148c
  classDef data fill:#e1f5fe,stroke:#0277bd,color:#01579b
  classDef service fill:#fce4ec,stroke:#c2185b,color:#880e4f
```
