mgaitan / sphinxcontrib-mermaid

Mermaid diagrams in yours sphinx powered docs
http://sphinxcontrib-mermaid-demo.readthedocs.io/en/latest/
Other
329 stars 94 forks source link

Support YAML frontmatter configuration #147

Closed kdeldycke closed 3 days ago

kdeldycke commented 1 month ago

Each mermaid diagram can be prefixed with a frontmatter configuration block to alter its default rendering. Example:

---
title: Hello Title
config:
  theme: base
  themeVariables:
    primaryColor: "#00ff00"
---
flowchart
    Hello --> World

This is the preferred way starting with Mermaid v10.5.0+ since %%{``}%% directives are now deprecated.

Unfortunately this syntax is not supported by sphinxcontrib-mermaid.

How to reproduce

Add the following diagram to any markdown file:

```mermaid
---
title: Hello Title
config:
  theme: base
  themeVariables:
    primaryColor: "#00ff00"
---
flowchart
    Hello --> World


It gets rendered with its default style:
<img width="125" alt="Screenshot 2024-08-13 at 16 57 23" src="https://github.com/user-attachments/assets/dd8a5582-f956-451e-906a-21667f34b54f">

Instead, I expect it to be rendered the same way it is [displayed in the official documentation](https://mermaid.js.org/config/configuration.html#frontmatter-config):
<img width="116" alt="Screenshot 2024-08-13 at 16 58 08" src="https://github.com/user-attachments/assets/cd8313b8-a747-423f-a4cd-942454c2d7c0">

This issue was produced in the following environment:
* Sphinx 7.3.7
* sphinxcontrib-mermaid 0.9.2
* myst-parser 3.0.1
* Python 3.12.4
kdeldycke commented 1 month ago

Note that GitHub is supporting these frontmatter configuration directives:

---
title: Hello Title
config:
  theme: base
  themeVariables:
    primaryColor: "#00ff00"
---
flowchart
    Hello --> World
kdeldycke commented 1 month ago

My particular use-case for this was to deactivate the rendering of values in a Sankey diagram like this:

---
config:
  sankey:
    showValues: false
---
sankey-beta

Agricultural 'waste',Bio-conversion,124.729
Bio-conversion,Liquid,0.597
Bio-conversion,Losses,26.862
Bio-conversion,Solid,280.322
Bio-conversion,Gas,81.144

As a temporary workaround, I deactivated globally value rendering for all Sankey diagrams by tweaking the Mermaid initialization in my Sphinx's conf.py configuration file:

mermaid_version = "latest"
mermaid_init_js = """
  const config = {
    startOnLoad: true,
    sankey: {
      showValues: false,
    },
  };
  mermaid.initialize(config);
"""
mgaitan commented 1 month ago

@kdeldycke are you interested in opening a PR for this? It seems a very valuable feature.