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
• YAML frontmatter — Set title and per-diagram config via Mermaid frontmatter in .mmd files and RST
• Auto class diagrams — Generate class hierarchy diagrams from Python code

Supported Diagram Types

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 .

Claude Code Skill (Optional)

This repository ships a mermaid-diagram skill for AI coding agents. It provides proactive diagram suggestions, syntax validation, and ready-made examples for all 6 supported diagram types.

Install it with gh skill install (preview, requires GitHub CLI 2.91+):

gh skill install drillan/sphinx-oceanid mermaid-diagram --agent claude-code

Supported --agent values: claude-code, github-copilot, cursor, codex, gemini, antigravity.

Use --scope user to install globally instead of per-project. See docs/install.md for details, version pinning, and update workflow.

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: True)
oceanid_zoom = False

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

# 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

YAML Frontmatter

External .mmd files can include YAML frontmatter to set the diagram title and per-diagram rendering options:

---
title: User Authentication Flow
config:
  bg: "#1a1b26"
  fg: "#a9b1d6"
---
flowchart TD
  A[Login Page] --> B{Valid credentials?}
  B -->|Yes| C[Dashboard]
  B -->|No| D[Error Message]

Frontmatter is also supported in RST inline content. In MyST Markdown, use directive options with JSON format for config. See the documentation for details.

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.