# remarkjs/remark-rehype architecture

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

- Interactive diagram: https://gitdiagram.com/remarkjs/remark-rehype
- Repository: https://github.com/remarkjs/remark-rehype

## Overview

##### Project type and purpose
- This is an open-source Node.js library (an ESM-only “unified” plugin) called remark-rehype.
- Its sole responsibility is to transform a Markdown syntax tree (mdast) into an HTML syntax tree (hast) so that downstream rehype (HTML) plugins can operate on it.
- It is not a full-stack application or microservice, but rather a bridge in a compiler-like processing pipeline.

##### File structure analysis
- Top-level files
- index.js            — module entry point that re-exports or wraps the code in lib/index.js
- lib/index.js        — main implementation of the remark-rehype transformer
- test.js             — example or test runner
- package.json        — metadata, dependencies, exports field pointing to index.js
- tsconfig.json       — TypeScript configuration for type checking
- .github/workflows   — CI definitions (build, test)
- .gitignore, .editorconfig, .prettierignore, .npmrc, license, readme.md
- No separate frontend/backend concerns—this is a library with one core component (the transformer).

##### Key architectural insights from README
- remark-rehype plugs into a unified pipeline:
[unified engine] → remark-parse → mdast → remark-rehype → hast → rehype-* plugins → rehype-stringify → HTML
- It supports two modes: bridge mode (passing through to another processor) and mutate mode (returning hast).
- It exports a transformer function plus helper functions (defaultFootnoteBackContent, defaultHandlers, etc.).
- It allows user customization via options (handlers, unknownHandler, footnote settings, allowDangerousHtml).

##### Main components
A. Unified processing engine
- Represents the central orchestrator that runs the pipeline.
B. remark-parse
- Takes raw Markdown text → produces mdast (Markdown AST).
C. remark-rehype
- Accepts mdast → transforms to hast (HTML AST).
- Core logic lives in lib/index.js.
- Exposes configuration options and handlers.
D. mdast-util-to-hast (optional subcomponent)
- Underlying utility invoked by remark-rehype to do the node-by-node conversion.
E. rehype plugins (post-bridge)
- Examples: rehype-document, rehype-format, rehype-sanitize, rehype-stringify.
- Operate on hast to modify or serialize it.
F. Output layer
- rehype-stringify (if used) serializes hast → HTML text.
G. External services / integrations
- File system (to-vfile) for reading/writing files.
- npm registry for distribution.
- CI pipelines for testing and publishing.

##### Relationships and data flow
1. Markdown file (input)
→ unified().use(remarkParse)
2. mdast tree
→ unified().use(remarkRehype, options)
3. hast tree
→ .use(rehypeRaw? → rehypeSanitize? → other rehype plugins…)
4. .use(rehypeStringify)
5. HTML string (output)
- Option injection into remark-rehype (handlers, footnote settings, allowDangerousHtml).

##### Architectural patterns and design principles
- Plugin-based pipeline (chain of responsibility).
- Separation of concerns: parsing → AST conversion → HTML transformation → serialization.
- Extensibility via user-provided handlers and passThrough lists.
- Immutable data flow (each plugin receives and returns a tree).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External I/O and Services
    subgraph "External Services / I/O"
        direction TB
        FS[(File System)]:::external
        NPM[(npm Registry)]:::external
        CI["CI Pipelines"]:::external
    end

    %% Processing Pipeline
    subgraph "Unified Processing Pipeline"
        direction TB

        MarkdownFile["Markdown File (input)"]:::data
        UnifiedEngine["Unified Engine"]:::engine

        subgraph "Parsing"
            direction TB
            RemarkParse["remark-parse (mdast)"]:::plugin
        end

        subgraph "Conversion / Bridge"
            direction TB
            remarkRehype["remark-rehype (mdast→hast)"]:::plugin
            libRegion["lib/index.js\n(Core logic)"]:::implementation
            remarkRehype --> libRegion
            Options["Options\n(handlers, footnote, allowDangerousHtml)"]:::config
            remarkRehype --> Options
            MdastToHast["mdast-util-to-hast"]:::utility
            remarkRehype --> MdastToHast
        end

        subgraph "Downstream HTML Plugins"
            direction TB
            rehypeRaw["rehype-raw"]:::htmlplugin
            rehypeSanitize["rehype-sanitize"]:::htmlplugin
            rehypeOther["rehype-* plugins"]:::htmlplugin
            rehypeStringify["rehype-stringify\n(HTML output)"]:::htmlplugin
        end

        MarkdownFile --> UnifiedEngine
        UnifiedEngine --> RemarkParse
        RemarkParse --> remarkRehype
        remarkRehype --> rehypeRaw
        rehypeRaw --> rehypeSanitize
        rehypeSanitize --> rehypeOther
        rehypeOther --> rehypeStringify
        rehypeStringify --> HTML["HTML String (output)"]:::data
    end

    %% Project Files and Metadata
    subgraph "Repository Files"
        direction TB
        EntryIndex["index.js"]:::project
        click EntryIndex "https://github.com/remarkjs/remark-rehype/blob/main/index.js"
        LibIndex["lib/index.js"]:::project
        click LibIndex "https://github.com/remarkjs/remark-rehype/blob/main/lib/index.js"
        TestRunner["test.js"]:::project
        click TestRunner "https://github.com/remarkjs/remark-rehype/blob/main/test.js"
        PackageMeta["package.json"]:::project
        click PackageMeta "https://github.com/remarkjs/remark-rehype/blob/main/package.json"
        TsConfig["tsconfig.json"]:::project
        click TsConfig "https://github.com/remarkjs/remark-rehype/blob/main/tsconfig.json"
        CI1[".github/workflows/main.yml"]:::project
        click CI1 "https://github.com/remarkjs/remark-rehype/blob/main/.github/workflows/main.yml"
        CI2[".github/workflows/bb.yml"]:::project
        click CI2 "https://github.com/remarkjs/remark-rehype/blob/main/.github/workflows/bb.yml"
        Readme["readme.md"]:::project
        click Readme "https://github.com/remarkjs/remark-rehype/blob/main/readme.md"
        GitIgnore[".gitignore"]:::project
        click GitIgnore "https://github.com/remarkjs/remark-rehype/blob/main/.gitignore"
        EditorConfig[".editorconfig"]:::project
        click EditorConfig "https://github.com/remarkjs/remark-rehype/blob/main/.editorconfig"
        PrettierIgnore[".prettierignore"]:::project
        click PrettierIgnore "https://github.com/remarkjs/remark-rehype/blob/main/.prettierignore"
        NpmRC[".npmrc"]:::project
        click NpmRC "https://github.com/remarkjs/remark-rehype/blob/main/.npmrc"
        License["license"]:::project
        click License "https://github.com/remarkjs/remark-rehype/tree/main/license"
    end

    %% Connections to CI and FS
    EntryIndex --> FS
    LibIndex --> FS
    PackageMeta --> NPM
    CI1 --> CI
    CI2 --> CI

    %% Styles
    classDef external fill:#dddddd,stroke:#888888,color:#333333;
    classDef engine fill:#cce5ff,stroke:#66b0ff,color:#004085;
    classDef plugin fill:#b3d7ff,stroke:#4da3ff,color:#004085;
    classDef implementation fill:#c8e6c9,stroke:#388e3c,color:#1b5e20;
    classDef config fill:#d4edda,stroke:#8fbc8f,color:#155724;
    classDef utility fill:#e2e3e5,stroke:#bcbec0,color:#818182;
    classDef htmlplugin fill:#ffe5b4,stroke:#ffbf69,color:#8a4f00;
    classDef data fill:#f8f9fa,stroke:#ced4da,color:#495057;
    classDef project fill:#f0f0f0,stroke:#a0a0a0,color:#303030;
```
