# laobubu/hypermd architecture

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

- Interactive diagram: https://gitdiagram.com/laobubu/hypermd
- Repository: https://github.com/laobubu/hypermd

## Overview

##### Project type and purpose
- HyperMD is a JavaScript/TypeScript front-end library that extends CodeMirror into a live Markdown editor.
- It’s not a full-stack application but a modular, front-end plugin framework with a build & demo environment, documentation, and tests.

##### File structure
- **src/**: the heart of the library
- core.ts + core/… – the central engine integrating with CodeMirror’s API
- addon/… – incremental extensions (“click,” “fold,” “hover,” etc.)
- mode/… – Markdown mode definitions for CodeMirror
- keymap/… – custom keyboard bindings
- **mode/**, **theme/**: SCSS and styling for the editor look & feel
- **dev/**: build pipelines (pre-build, post-build), doc generators, utility scripts
- **docs/**: user manual, quick-start, multilingual guides, example pages
- **test/**: unit/integration tests, bootstrap, dummy editors
- Root configs: package.json, tsconfig.json, rollup.config.js, .travis.yml

##### README insights
- Core purpose: “Breaks the wall between writing and preview”
- Extensible via addons & powerpacks
- Supports multiple module loaders: CommonJS, AMD (RequireJS), bundlers (webpack, Parcel)

1. External CodeMirror Core (external dependency)
2. HyperMD Core Engine (src/core)
3. Addon Modules (src/addon/*)
4. Mode Modules (src/mode/*)
5. KeyMap Module (src/keymap)
6. PowerPacks (src/powerpack/*)
7. Theme & Styles (mode/*.scss, theme/*.scss)
8. Build & Tooling (dev/*, rollup.config.js)
9. Demo Site (demo/*)
10. Documentation (docs/*)
11. Test Suite (test/*)

- HyperMD Core ↔ CodeMirror API (initialize editor, listen events)
- Addons → HyperMD Core (extend behaviors)
- Modes → Core (tokenize/render Markdown syntax)
- KeyMap → Core (bind shortcuts)
- PowerPacks → Core (on-the-fly third-party integration)
- Styles → Core/UI (SCSS compiled into CSS)
- Build Tools → src → bundle outputs (dist/… as npm package or demo assets)
- Demo Site ← Bundled library + vendor libs
- Tests → src (validate each module)
- Docs (static site) ← markdown ≔ docgen scripts in dev/docgen

c. Architectural patterns & principles
- Modular design: each feature in its own folder, published as a unified package
- Plugin/extension pattern: core provides hooks, addons & powerpacks register themselves
- Build pipeline: pre-build → TypeScript transpile → rollup bundling → post-build (docs, examples)
- Multi-target packaging: UMD for browser, CommonJS for Node/npm, AMD support

d. Key technologies & frameworks
- TypeScript → transpilation APIs (tsconfig.json, dev build scripts)
- Rollup.js → bundling for npm distribution (rollup.config.js)
- CodeMirror v5 → in-browser editor core
- RequireJS / webpack / Parcel → module loading strategies in demo & users’ apps
- SCSS → theme styling

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Dependency
    subgraph "External Dependency"
        CodeMirror["CodeMirror v5"]:::external
    end

    %% Source Components
    subgraph "Source Components"
        Core["HyperMD Core\n(src/core)"]:::core
        Addons["Addon Modules\n(src/addon/)"]:::extension
        Modes["Mode Modules\n(src/mode/)"]:::extension
        KeyMap["KeyMap Module\n(src/keymap/hypermd.ts)"]:::extension
        PowerPacks["PowerPacks\n(src/powerpack/)"]:::power
        Styles["Theme & Styles\nmode/hypermd.scss\ntheme/hypermd-light.scss"]:::extension
    end

    %% Build & Tooling
    subgraph "Build & Tooling"
        PreBuild["Pre-build\n(dev/pre-build.js)"]:::tools
        Transpile["Transpile TS\n(tsconfig.json)"]:::tools
        Bundle["Rollup Bundling\n(rollup.config.js)"]:::tools
        DocGen["Doc Generation\n(dev/docgen/)"]:::tools
        PostBuild["Post-build\n(dev/post-build.js)"]:::tools
    end

    %% Outputs
    subgraph "Outputs"
        Dist["Dist Package\n(UMD/CJS/AMD)"]:::output
        Demo["Demo Site\n(demo/)"]:::output
        Docs["Documentation\n(docs/)"]:::output
        Tests["Test Suite\n(test/)"]:::output
    end

    %% Relationships
    CodeMirror -->|"init & API"| Core
    Addons -->|"hooks→"| Core
    Modes -->|"tokenize/render→"| Core
    KeyMap -->|"shortcuts→"| Core
    PowerPacks -->|"integration→"| Core
    Styles -->|"compile CSS→"| Core

    Core --> PreBuild
    PreBuild --> Transpile
    Transpile --> Bundle
    Bundle --> PostBuild

    Bundle --> Dist
    Dist --> Demo
    DocGen --> Docs
    Tests --> Core

    %% Click Events
    click Core "https://github.com/laobubu/hypermd/blob/master/src/core.ts"
    click Core "https://github.com/laobubu/hypermd/tree/master/src/core/"
    click Addons "https://github.com/laobubu/hypermd/tree/master/src/addon/"
    click Modes "https://github.com/laobubu/hypermd/tree/master/src/mode/"
    click KeyMap "https://github.com/laobubu/hypermd/blob/master/src/keymap/hypermd.ts"
    click PowerPacks "https://github.com/laobubu/hypermd/tree/master/src/powerpack/"
    click Styles "https://github.com/laobubu/hypermd/blob/master/mode/hypermd.scss"
    click Styles "https://github.com/laobubu/hypermd/blob/master/theme/hypermd-light.scss"
    click PreBuild "https://github.com/laobubu/hypermd/blob/master/dev/pre-build.js"
    click Transpile "https://github.com/laobubu/hypermd/blob/master/tsconfig.json"
    click Bundle "https://github.com/laobubu/hypermd/blob/master/rollup.config.js"
    click DocGen "https://github.com/laobubu/hypermd/tree/master/dev/docgen/"
    click Demo "https://github.com/laobubu/hypermd/tree/master/demo/"
    click Docs "https://github.com/laobubu/hypermd/tree/master/docs/"
    click Tests "https://github.com/laobubu/hypermd/tree/master/test/"

    %% Styles
    classDef core fill:#cce5ff,stroke:#004085;
    classDef extension fill:#d4edda,stroke:#155724;
    classDef power fill:#fff3cd,stroke:#856404;
    classDef tools fill:#e2e3e5,stroke:#d6d8db;
    classDef output fill:#bee5eb,stroke:#0c5460;
    classDef external fill:#f8d7da,stroke:#721c24;
```
