# lepture/mistune architecture

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

- Interactive diagram: https://gitdiagram.com/lepture/mistune
- Repository: https://github.com/lepture/mistune

## Overview

##### Project type and purpose
- Mistune v3 is an open-source Python library for parsing Markdown into various output formats (HTML, Markdown, reStructuredText, etc.).
- It exposes both a simple API (`mistune.html`) for users and a plugin/directive architecture for extensibility.

##### File structure
- Top-level “src/mistune”: the core library package.
- core.py, block_parser.py, inline_parser.py, list_parser.py – the parsing engine.
- renderers/ – output format modules (html.py, markdown.py, rst.py, plus base classes).
- directives/ – rst-style directives (admonition, toc, include, etc.).
- plugins/ – optional features (footnotes, tables, math, etc.).
- helpers.py, util.py – shared utilities.
- __main__.py – CLI entry point (`python -m mistune`).
- “tests/”: automated test suites covering parsing, rendering, directives, plugins.
- “benchmark/”: performance measurement scripts and sample cases.
- “docs/”: Sphinx documentation sources.
- Packaging/config: setup.py, pyproject.toml, MANIFEST.in, Makefile, CI workflows in .github/workflows.

##### README for additional insights
- Confirms it’s a re-designed v3 library focusing on speed and extensibility.
- Mentions CLI usage, benchmarks, plugin system, and installation via PyPI.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Layer
    subgraph "User Layer"
        User["User (Python Developer)"]:::external
    end

    %% Entry Points
    subgraph "Entry Points"
        CLI["CLI Interface"]:::api
        API["Public API Layer"]:::api
    end

    %% Core Pipeline
    subgraph "Core Pipeline"
        subgraph "Parser Layer"
            Core["core.py"]:::core
            BlockParser["block_parser.py"]:::core
            InlineParser["inline_parser.py"]:::core
            ListParser["list_parser.py"]:::core
        end
        AST["AST / Token Stream"]:::core
        subgraph "Renderer Layer"
            RenderInit["__init__.py"]:::renderer
            HTMLRenderer["html.py"]:::renderer
            MarkdownRenderer["markdown.py"]:::renderer
            RstRenderer["rst.py"]:::renderer
            ListRenderer["_list.py"]:::renderer
        end
    end

    %% Extension Points
    subgraph "Extension Points"
        subgraph "Directive Subsystem"
            DirectivesDir["directives/"]:::extension
        end
        subgraph "Plugin Subsystem"
            PluginsDir["plugins/"]:::extension
        end
    end

    %% Utilities
    Utilities["helpers.py / util.py"]:::utility

    %% Output
    Output["Final Output String"]:::core

    %% Auxiliary Systems
    subgraph "Auxiliary Systems"
        Tests["tests/"]:::aux
        Benchmark["benchmark/"]:::aux
        Docs["docs/"]:::aux
        CI["GitHub Actions CI"]:::aux
        Packaging["setup.py / pyproject.toml / MANIFEST.in / Makefile"]:::aux
    end

    %% Connections
    User -->|invokes| CLI
    User -->|imports| API
    CLI -->|calls| API
    API -->|configures| Core
    API -->|configures| BlockParser
    API -->|configures| InlineParser
    API -->|configures| ListParser

    Core -->|"produces"| AST
    BlockParser --> AST
    InlineParser --> AST
    ListParser --> AST

    AST --> RenderInit
    AST --> HTMLRenderer
    AST --> MarkdownRenderer
    AST --> RstRenderer
    AST --> ListRenderer
    RenderInit --> Output
    HTMLRenderer --> Output
    MarkdownRenderer --> Output
    RstRenderer --> Output
    ListRenderer --> Output

    Core -.-> Utilities
    BlockParser -.-> Utilities
    InlineParser -.-> Utilities
    ListParser -.-> Utilities
    RenderInit -.-> Utilities
    HTMLRenderer -.-> Utilities
    MarkdownRenderer -.-> Utilities
    RstRenderer -.-> Utilities
    ListRenderer -.-> Utilities

    BlockParser -->|handles directives| DirectivesDir
    InlineParser -->|handles directives| DirectivesDir
    Core -->|registers| PluginsDir
    RenderInit -->|plugins hook| PluginsDir

    CI --> Tests
    CI --> Benchmark
    CI --> Docs

    %% Click Events
    click CLI "https://github.com/lepture/mistune/blob/main/src/mistune/__main__.py"
    click API "https://github.com/lepture/mistune/blob/main/src/mistune/__init__.py"
    click Core "https://github.com/lepture/mistune/blob/main/src/mistune/core.py"
    click BlockParser "https://github.com/lepture/mistune/blob/main/src/mistune/block_parser.py"
    click InlineParser "https://github.com/lepture/mistune/blob/main/src/mistune/inline_parser.py"
    click ListParser "https://github.com/lepture/mistune/blob/main/src/mistune/list_parser.py"
    click RenderInit "https://github.com/lepture/mistune/blob/main/src/mistune/renderers/__init__.py"
    click HTMLRenderer "https://github.com/lepture/mistune/blob/main/src/mistune/renderers/html.py"
    click MarkdownRenderer "https://github.com/lepture/mistune/blob/main/src/mistune/renderers/markdown.py"
    click RstRenderer "https://github.com/lepture/mistune/blob/main/src/mistune/renderers/rst.py"
    click ListRenderer "https://github.com/lepture/mistune/blob/main/src/mistune/renderers/_list.py"
    click DirectivesDir "https://github.com/lepture/mistune/tree/main/src/mistune/directives/"
    click PluginsDir "https://github.com/lepture/mistune/tree/main/src/mistune/plugins/"
    click Utilities "https://github.com/lepture/mistune/blob/main/src/mistune/helpers.py"
    click Utilities "https://github.com/lepture/mistune/blob/main/src/mistune/util.py"
    click Tests "https://github.com/lepture/mistune/tree/main/tests/"
    click Benchmark "https://github.com/lepture/mistune/tree/main/benchmark/"
    click Docs "https://github.com/lepture/mistune/tree/main/docs/"
    click CI "https://github.com/lepture/mistune/blob/main/.github/workflows/tests.yml"
    click Packaging "https://github.com/lepture/mistune/blob/main/setup.py"
    click Packaging "https://github.com/lepture/mistune/blob/main/pyproject.toml"
    click Packaging "https://github.com/lepture/mistune/blob/main/MANIFEST.in"
    click Packaging "https://github.com/lepture/mistune/tree/main/Makefile"

    %% Styles
    classDef external fill:#F3F4F6,stroke:#333,stroke-width:1px
    classDef api fill:#E0F2FE,stroke:#3B82F6,stroke-width:1px
    classDef core fill:#FEF3C7,stroke:#D97706,stroke-width:1px
    classDef renderer fill:#FEF3C7,stroke:#D97706,stroke-width:1px
    classDef extension fill:#ECFDF5,stroke:#10B981,stroke-width:1px
    classDef utility fill:#F0F9FF,stroke:#0EA5E9,stroke-width:1px
    classDef aux fill:#FDF2F8,stroke:#DB2777,stroke-width:1px
```
