# mgaitan/sphinxcontrib-mermaid architecture

> Architecture diagram of the GitHub repository mgaitan/sphinxcontrib-mermaid, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mgaitan/sphinxcontrib-mermaid
- Repository: https://github.com/mgaitan/sphinxcontrib-mermaid

## Overview

sphinxcontrib-mermaid is a Sphinx extension for authoring Mermaid diagrams and class-inheritance diagrams in documentation. A document author supplies inline or external Mermaid markup, or names classes/modules for an autoclass tree; Sphinx then emits raw Mermaid for HTML or renders image output for supported builders. The extension also supports diagram options, translations, zoom and fullscreen behavior. The graph reflects the README and sampled implementation; some builder and configuration details were not included in the source excerpts.

Main entry points: [`sphinxcontrib/mermaid/__init__.py`](https://github.com/mgaitan/sphinxcontrib-mermaid/blob/master/sphinxcontrib/mermaid/__init__.py) (Builder output), [`sphinxcontrib/mermaid/autoclassdiag.py`](https://github.com/mgaitan/sphinxcontrib-mermaid/blob/master/sphinxcontrib/mermaid/autoclassdiag.py) (Class discovery), [`sphinxcontrib/mermaid/exceptions.py`](https://github.com/mgaitan/sphinxcontrib-mermaid/blob/master/sphinxcontrib/mermaid/exceptions.py) (Mermaid errors)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Diagram authoring"]
  node_mermaid_directive["Mermaid directive<br/>[__init__.py]"]
  node_external_mermaid_source["External Mermaid source"]
end

subgraph group_rendering["Rendering"]
  node_builder_output["Builder output<br/>[__init__.py]"]
  node_mermaid_cli["Mermaid CLI"]
  node_pdfcrop["PDF cropping"]
end

subgraph group_class_diagrams["Class diagrams"]
  node_autoclass_directive["Autoclass directive<br/>[__init__.py]"]
  node_class_discovery["Class discovery<br/>[autoclassdiag.py]"]
  node_mermaid_errors["Mermaid errors<br/>[exceptions.py]"]
end

subgraph group_html_features["HTML enhancements"]
  node_html_assets["HTML assets<br/>[__init__.py]"]
  node_mermaid_runtime["Mermaid JavaScript"]
  node_zoom_fullscreen["Zoom and fullscreen<br/>[__init__.py]"]
  node_d3["D3 library"]
end

node_author(("Documentation author"))
node_sphinx["Sphinx build"]

node_author -->|"writes markup"| node_mermaid_directive
node_author -->|"names classes"| node_autoclass_directive
node_sphinx -->|"processes directive"| node_mermaid_directive
node_mermaid_directive -->|"reads source"| node_external_mermaid_source
node_mermaid_directive -->|"provides diagram"| node_builder_output
node_sphinx -->|"processes directive"| node_autoclass_directive
node_autoclass_directive -->|"generates hierarchy"| node_class_discovery
node_class_discovery -->|"raises errors"| node_mermaid_errors
node_builder_output -->|"renders diagrams"| node_mermaid_cli
node_builder_output -->|"crops PDF"| node_pdfcrop
node_builder_output -->|"emits HTML"| node_html_assets
node_html_assets -->|"loads runtime"| node_mermaid_runtime
node_html_assets -->|"configures features"| node_zoom_fullscreen
node_html_assets -.->|"loads when configured"| node_d3

click node_mermaid_directive "https://github.com/mgaitan/sphinxcontrib-mermaid/blob/master/sphinxcontrib/mermaid/__init__.py"
click node_autoclass_directive "https://github.com/mgaitan/sphinxcontrib-mermaid/blob/master/sphinxcontrib/mermaid/__init__.py"
click node_class_discovery "https://github.com/mgaitan/sphinxcontrib-mermaid/blob/master/sphinxcontrib/mermaid/autoclassdiag.py"
click node_mermaid_errors "https://github.com/mgaitan/sphinxcontrib-mermaid/blob/master/sphinxcontrib/mermaid/exceptions.py"
click node_builder_output "https://github.com/mgaitan/sphinxcontrib-mermaid/blob/master/sphinxcontrib/mermaid/__init__.py"
click node_html_assets "https://github.com/mgaitan/sphinxcontrib-mermaid/blob/master/sphinxcontrib/mermaid/__init__.py"
click node_zoom_fullscreen "https://github.com/mgaitan/sphinxcontrib-mermaid/blob/master/sphinxcontrib/mermaid/__init__.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mermaid_directive,node_external_mermaid_source toneBlue
class node_builder_output,node_mermaid_cli,node_pdfcrop toneAmber
class node_autoclass_directive,node_class_discovery,node_mermaid_errors toneMint
class node_html_assets,node_mermaid_runtime,node_zoom_fullscreen,node_d3 toneRose
class node_author,node_sphinx toneIndigo
```

## Components

### Diagram authoring

- [Mermaid directive](https://github.com/mgaitan/sphinxcontrib-mermaid/blob/master/sphinxcontrib/mermaid/__init__.py): `sphinxcontrib/mermaid/__init__.py`
- **External Mermaid source**

### Rendering

- [Builder output](https://github.com/mgaitan/sphinxcontrib-mermaid/blob/master/sphinxcontrib/mermaid/__init__.py): `sphinxcontrib/mermaid/__init__.py`
- **Mermaid CLI**
- **PDF cropping**

### Class diagrams

- [Autoclass directive](https://github.com/mgaitan/sphinxcontrib-mermaid/blob/master/sphinxcontrib/mermaid/__init__.py): `sphinxcontrib/mermaid/__init__.py`
- [Class discovery](https://github.com/mgaitan/sphinxcontrib-mermaid/blob/master/sphinxcontrib/mermaid/autoclassdiag.py): `sphinxcontrib/mermaid/autoclassdiag.py`
- [Mermaid errors](https://github.com/mgaitan/sphinxcontrib-mermaid/blob/master/sphinxcontrib/mermaid/exceptions.py): `sphinxcontrib/mermaid/exceptions.py`

### HTML enhancements

- [HTML assets](https://github.com/mgaitan/sphinxcontrib-mermaid/blob/master/sphinxcontrib/mermaid/__init__.py): `sphinxcontrib/mermaid/__init__.py`
- **Mermaid JavaScript**
- [Zoom and fullscreen](https://github.com/mgaitan/sphinxcontrib-mermaid/blob/master/sphinxcontrib/mermaid/__init__.py): `sphinxcontrib/mermaid/__init__.py`
- **D3 library**

### Other components

- **Documentation author**
- **Sphinx build**

## Connections

- Documentation author → Mermaid directive: writes markup (evidence: `README.md`)
- Documentation author → Autoclass directive: names classes (evidence: `README.md`)
- Sphinx build → Mermaid directive: processes directive (evidence: `README.md`)
- Mermaid directive → External Mermaid source: reads source (evidence: `sphinxcontrib/mermaid/__init__.py`)
- Mermaid directive → Builder output: provides diagram (evidence: `README.md`)
- Sphinx build → Autoclass directive: processes directive (evidence: `README.md`)
- Autoclass directive → Class discovery: generates hierarchy (evidence: `sphinxcontrib/mermaid/__init__.py`)
- Class discovery → Mermaid errors: raises errors (evidence: `sphinxcontrib/mermaid/autoclassdiag.py`)
- Builder output → Mermaid CLI: renders diagrams (evidence: `README.md`)
- Builder output → PDF cropping: crops PDF (evidence: `sphinxcontrib/mermaid/__init__.py`)
- Builder output → HTML assets: emits HTML (evidence: `README.md`)
- HTML assets → Mermaid JavaScript: loads runtime (evidence: `README.md`)
- HTML assets → Zoom and fullscreen: configures features (evidence: `sphinxcontrib/mermaid/__init__.py`)
- HTML assets → D3 library: loads when configured (evidence: `sphinxcontrib/mermaid/__init__.py`)
