Getting Started¶

Install¶

pip install sphinx-oceanid

For other installation methods, see Installation.

Enable the extension¶

Add sphinx_oceanid to the extensions list in your Sphinx conf.py:

extensions = ["sphinx_oceanid"]

No additional configuration is required. sphinx-oceanid works out of the box using the CDN-hosted beautiful-mermaid library.

Write your first diagram¶

Use the mermaid directive in your documentation:

RST

.. mermaid::

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

MyST

```{mermaid}
flowchart LR
  A[Start] --> B[Process] --> C[End]
```

For the full list of directive options and usage examples, see sphinx-oceanid documentation.

Preview¶

Mermaid diagrams require HTTP serving — opening built HTML via file:// will not render diagrams due to browser CORS restrictions.

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

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

For Makefile setup and local bundle configuration, see Installation.