sphinx-revealjs製スライドにMermaidによる図を表示する

はじめに

PyCon mini Shizuoka 2024 continue、1日ありがとうございました！ nikkieです。

登壇準備からSphinxまわりの小ネタです。
スライド作成にはattakeiさんのsphinx-revealjsを使っています。

目次

• はじめに
• 目次
• sphinx-revealjs製スライドにMermaidによる図を表示
• SphinxのドキュメントにMermaidによる図を埋め込んだことがあった
• sphinx-revealjs製スライドでも埋め込める理由
• 裏話
• 終わりに

sphinx-revealjs製スライドにMermaidによる図を表示

こちらのスライドがそれです。
https://ftnext.github.io/2025-slides/pyconshizu/logging-with-nullhandler.html#/24/2

Logging Flowの図（簡易版）をMermaidで書いています¹。

SphinxのドキュメントにMermaidによる図を埋め込んだことがあった

2023年のXP祭り ワークショップ²の資料にて
https://ftnext.github.io/small-technical-2023/chapter-refactoring.html#id7

sphinxcontrib-mermaidを使っています。

この拡張によりmermaidディレクティブが有効になります³

.. mermaid::

    sequenceDiagram
        省略

sphinx-revealjs製スライドでも埋め込める理由

sphinx-revealjsでもmermaidディレクティブを使いました。
https://github.com/ftnext/2025-slides/blob/75a2490ecc9d3a7b805f69dff4d51954ff8f31b9/source/pyconshizu/gleanings.rst.txt#L153

.. mermaid:: logging-propagate-flow.mmd

（ファイルも指定できるのです）

sphinx-revealjsと組合せても動く理由を見ていきましょう。
sphinxcontrib-mermaidのREADMEより

the HTML builder will simply render this as a div tag with class="mermaid"

より具体的に知るべく実装を見ると
https://github.com/mgaitan/sphinxcontrib-mermaid/blob/1.0.0/sphinxcontrib/mermaid/__init__.py#L518-L525

def setup(app):
    app.add_node(
        mermaid,
        html=(html_visit_mermaid, None),
        # 省略
    )
    # 省略

html=(html_visit_mermaid, None)は、HTMLビルダーのvisitor functionの設定です。
ref: https://www.sphinx-doc.org/ja/master/extdev/appapi.html#sphinx.application.Sphinx.add_node

これまでの経験から、sphinx-revealjsはHTMLビルダーと理解しています。
sphinx.ext.githubpagesが動くかを見たときに、RevealjsHTMLBuilderはStandaloneHTMLBuilderを継承しており、アウトプット形式がHTMLであることを確認しました。

Sphinxの挙動をより詳細に理解する余地はありますが、sphinxcontrib-mermaidはsphinx-revealjsと一緒に動いているので、今回はここまでとします。

裏話

• Mermaidで画像にして⁴スライドに載せる方法もありましたが、致命的にうまくいっていないわけでもないので決行しました
• スライドの背景色を黒から白に変えたのは、mermaidディレクティブで黒い線と文字で描画するために何も見えなくなる問題に対処して
  • revealjs-sectionディレクティブに:data-background-color:を指定
    • ref: https://sphinx-revealjs.readthedocs.io/en/stable/directives/#directive-revealjs-section
  • mermaidディレクティブでスタイルを調整できるのかも（宿題）
• 該当スライドのリロードが必要になる理由はよく分かっていません（宿題事項）
  • 記事を書いていて気付いたのですが、Reveal.js側のMermaid埋め込みの情報を見に行ってもいいかも

終わりに

sphinx-revealjsのスライドにsphinxcontrib-mermaidでMermaidによる図を埋め込めます！
よりうまく使いこなす伸びしろがありそうですが、また次に触るときに考えたいと思います。