sphinx-oceanid 0.1.1

Mermaid diagrams in Sphinx, powered by beautiful-mermaid

sphinx-oceanid

Mermaid diagrams in Sphinx, powered by beautiful-mermaid.

Features

• beautiful-mermaid rendering — Uses ELK.js-based layout engine for high-quality SVG output
• CSS variable theming — Automatic dark/light theme detection with instant switching (no re-render)
• Zero-config — Works out of the box with CDN-hosted beautiful-mermaid
• sphinx-revealjs support — Lazy rendering for hidden slides via IntersectionObserver (example)
• Pan & zoom — Native Pointer Events + SVG transform (no d3.js dependency)
• Fullscreen modal — View diagrams in a viewport-sized overlay
• External file support — Reference .mmd files instead of inline code
• Auto class diagrams — Generate class hierarchy diagrams from Python code

Supported Diagram Types

Type	Alias
flowchart	graph
sequenceDiagram
classDiagram
stateDiagram	stateDiagram-v2
erDiagram
xychart-beta

Unsupported diagram types produce explicit warnings (or errors), never silent degradation.

Installation

sphinx-oceanid requires Python 3.13+.

pip install sphinx-oceanid

From source:

pip install git+https://github.com/drillan/sphinx-oceanid.git

Or clone and install locally:

git clone https://github.com/drillan/sphinx-oceanid.git
cd sphinx-oceanid
pip install .

Quick Start

Add the extension to your conf.py:

extensions = ["sphinx_oceanid"]

Then use the mermaid directive in your reStructuredText files:

.. mermaid::

   flowchart LR
     A[Start] --> B[Process] --> C[End]

Or in Markdown (MyST) files:

```{mermaid}
sequenceDiagram
  Alice->>Bob: Hello
  Bob-->>Alice: Hi!
```

Build and preview — Mermaid diagrams require HTTP serving (file:// will not render due to CORS):

# Quick static server (no extra dependencies)
make -C docs serve

# Live reload (requires sphinx-autobuild)
pip install sphinx-oceanid[preview]
make -C docs livehtml

See docs/install.md for Makefile setup instructions.

Configuration

All configuration options use the oceanid_ prefix in conf.py:

# conf.py
extensions = ["sphinx_oceanid"]

# Theme (default: "auto" — detects dark/light from Sphinx theme)
oceanid_theme = "auto"
oceanid_theme_dark = "zinc-dark"
oceanid_theme_light = "zinc-light"

# Enable zoom on all diagrams (default: False)
oceanid_zoom = True

# Enable fullscreen modal (default: False)
oceanid_fullscreen = True

# Action for unsupported diagram types: "warning" or "error" (default: "warning")
oceanid_unsupported_action = "warning"

Directive Options

.. mermaid::
   :name: my-diagram
   :alt: Description for accessibility
   :align: center
   :caption: Diagram caption (rendered as <figcaption>)
   :title: Mermaid native title (rendered inside the diagram)
   :zoom:
   :config: {"theme": "forest"}

   flowchart LR
     A --> B --> C

Auto Class Diagrams

Generate class hierarchy diagrams from Python code:

.. autoclasstree:: mypackage.MyClass
   :full:
   :namespace: mypackage
   :caption: Class hierarchy

Documentation

Full documentation is available at drillan.github.io/sphinx-oceanid or in the docs/ directory.

License

BSD-3-Clause. See LICENSE for details.