# swiftlang/swift-markdown architecture

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

- Interactive diagram: https://gitdiagram.com/swiftlang/swift-markdown
- Repository: https://github.com/swiftlang/swift-markdown

## Overview

##### Main Components

a) Parser Layer:
- Entry point through Document parser
- CommonMarkConverter (uses cmark-gfm)
- To BlockDirectiveParser and other parsing components

b) Core Data Structure Layer:
- Document as the root node
- Markup hierarchy with different node types:
- Block Nodes (BlockQuote, Lists, CodeBlock, etc.)
- Inline Nodes (Link, Emphasis, Text, etc.)
- Table-related nodes
- Custom nodes

c) Processing Layer:
- Visitors (MarkupVisitor)
- Walkers (MarkupWalker)
- Rewriters (MarkupRewriter)
- Formatters (HTMLFormatter, MarkupFormatter)

d) Utility Layer:
- Source location tracking
- Atomic operations
- Range management

**[Input: String/URL] → [Parser Layer] → [Core Data Structure Layer] → [Processing Layer] → [Output]**
- ↑↓
- [Utility Layer]

##### Important Relationships to Highlight

- How the Document parser creates the initial markup tree
- Hierarchical relationship between different types of nodes
- Demonstrate how Visitors/Walkers traverse the markup tree
- How Rewriters can modify the structure while maintaining immutability

##### Key Technical Aspects to Emphasize

- Copy-on-write value types for the markup tree
- Thread-safety mechanisms
- Immutable/persistent data structures
- Integration with cmark-gfm for parsing

##### Implementation Details

**[Document Parser]**
- ↓
**[Markup Tree]**

- [Block Nodes]
- Container Blocks (BlockQuote, Lists)
- Leaf Blocks (CodeBlock, Heading)
- Tables

- [Inline Nodes]
- Containers (Emphasis, Link)
- Leaves (Text, InlineCode)

- [Processing]
- Visitors
- Walkers
- Rewriters

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Input
        I[String/URL Input]:::input
    end

    subgraph "Parser Layer"
        DC["Document Parser"]:::parser
        click DC "https://github.com/swiftlang/swift-markdown/blob/main/Sources/Markdown/Parser/CommonMarkConverter.swift"
        BDP["Block Directive Parser"]:::parser
        click BDP "https://github.com/swiftlang/swift-markdown/blob/main/Sources/Markdown/Parser/BlockDirectiveParser.swift"
        PO["Parse Options"]:::parser
        click PO "https://github.com/swiftlang/swift-markdown/blob/main/Sources/Markdown/Parser/ParseOptions.swift"
    end

    subgraph "Core Data Structure"
        DOC["Document"]:::core
        click DOC "https://github.com/swiftlang/swift-markdown/blob/main/Sources/Markdown/Base/Document.swift"
        MB["Markup Base"]:::core
        click MB "https://github.com/swiftlang/swift-markdown/blob/main/Sources/Markdown/Base/Markup.swift"
        
        subgraph "Node Types"
            BN["Block Nodes"]:::nodes
            click BN "https://github.com/swiftlang/swift-markdown/tree/main/Sources/Markdown/Block Nodes/"
            IN["Inline Nodes"]:::nodes
            click IN "https://github.com/swiftlang/swift-markdown/tree/main/Sources/Markdown/Inline Nodes/"
            TN["Table Nodes"]:::nodes
            click TN "https://github.com/swiftlang/swift-markdown/tree/main/Sources/Markdown/Block Nodes/Tables/"
        end

        subgraph "Structural Components"
            BC["Block Containers"]:::struct
            click BC "https://github.com/swiftlang/swift-markdown/blob/main/Sources/Markdown/Structural Restrictions/BlockContainer.swift"
            IC["Inline Containers"]:::struct
            click IC "https://github.com/swiftlang/swift-markdown/blob/main/Sources/Markdown/Structural Restrictions/InlineContainer.swift"
            BBC["Basic Block Container"]:::struct
            click BBC "https://github.com/swiftlang/swift-markdown/blob/main/Sources/Markdown/Structural Restrictions/BasicBlockContainer.swift"
            BIC["Basic Inline Container"]:::struct
            click BIC "https://github.com/swiftlang/swift-markdown/blob/main/Sources/Markdown/Structural Restrictions/BasicInlineContainer.swift"
        end
    end

    subgraph "Processing Layer"
        MV["Markup Visitor"]:::process
        click MV "https://github.com/swiftlang/swift-markdown/blob/main/Sources/Markdown/Visitor/MarkupVisitor.swift"
        MW["Markup Walker"]:::process
        click MW "https://github.com/swiftlang/swift-markdown/blob/main/Sources/Markdown/Walker/MarkupWalker.swift"
        MR["Markup Rewriter"]:::process
        click MR "https://github.com/swiftlang/swift-markdown/blob/main/Sources/Markdown/Rewriter/MarkupRewriter.swift"
        
        subgraph "Formatters"
            HF["HTML Formatter"]:::format
            click HF "https://github.com/swiftlang/swift-markdown/blob/main/Sources/Markdown/Walker/Walkers/HTMLFormatter.swift"
            MF["Markup Formatter"]:::format
            click MF "https://github.com/swiftlang/swift-markdown/blob/main/Sources/Markdown/Walker/Walkers/MarkupFormatter.swift"
        end
    end

    subgraph "Utility Layer"
        SL["Source Location"]:::util
        click SL "https://github.com/swiftlang/swift-markdown/blob/main/Sources/Markdown/Infrastructure/SourceLocation.swift"
        AO["Atomic Operations"]:::util
        click AO "https://github.com/swiftlang/swift-markdown/blob/main/Sources/Markdown/Utility/AtomicCounter.swift"
        RA["Range Adjuster"]:::util
        click RA "https://github.com/swiftlang/swift-markdown/blob/main/Sources/Markdown/Parser/RangeAdjuster.swift"
        RT["Range Tracker"]:::util
        click RT "https://github.com/swiftlang/swift-markdown/blob/main/Sources/Markdown/Parser/RangerTracker.swift"
        RH["Replacement Handler"]:::util
        click RH "https://github.com/swiftlang/swift-markdown/blob/main/Sources/Markdown/Infrastructure/Replacement.swift"
    end

    subgraph Output
        O[Formatted Output]:::output
    end

    %% Relationships
    I --> DC
    DC --> BDP
    DC --> PO
    DC --> DOC
    DOC --> MB
    MB --> BN & IN & TN
    BN --> BC
    IN --> IC
    BC --> BBC
    IC --> BIC
    
    DOC --> MV & MW & MR
    MV & MW & MR --> HF & MF
    HF & MF --> O

    %% Utility connections
    SL & AO & RA & RT & RH -.-> DOC
    SL & AO & RA & RT & RH -.-> DC

    %% Styles
    classDef input fill:#B3E5FC,stroke:#0288D1
    classDef parser fill:#C8E6C9,stroke:#388E3C
    classDef core fill:#FFF9C4,stroke:#FBC02D
    classDef nodes fill:#FFE0B2,stroke:#F57C00
    classDef struct fill:#E1BEE7,stroke:#7B1FA2
    classDef process fill:#FFCCBC,stroke:#E64A19
    classDef format fill:#F8BBD0,stroke:#C2185B
    classDef util fill:#CFD8DC,stroke:#546E7A
    classDef output fill:#B3E5FC,stroke:#0288D1
```
