Sphinx Mermaid diagrams are not rendering

[pbilling]

Instead of diagrams, the build passes but I only see the source text.

Sphix mermaid docs for markdown support: https://sphinxcontrib-mermaid-demo.readthedocs.io/en/latest/#markdown-support.

These docs recommend referencing the minimum configuration from their tests: https://github.com/mgaitan/sphinxcontrib-mermaid/blob/master/tests/roots/test-markdown/conf.py.

I tried adding all (3) of these elements to my own conf.py

These work fine:

extensions = ['sphinxcontrib.mermaid', 'myst_parser']
exclude_patterns = ['_build']

This section breaks my build:

source_suffix = {
    '.md': 'markdown'
}

Error excerpt:

Sphinx error:
root file /home/docs/checkouts/readthedocs.org/user_builds/trellis-data-management/checkouts/latest/index.md not found

[pbilling]

There is no index.md, instead there is an index.rst. In the test, the index is also markdown formatted.

"source_suffix" indicates the format of source files. By explicitly specifying markdown as a source files, maybe I am implying that .rst files are not source files and this is different from the default mode, so now it doesn't recognized index.rst because it's not markdown.

[pbilling]

I added '*.rst' to as a 'source_suffix' and that fixed my build issue but the diagrams still don't render. I don't think the source_suffix was an issue to begin with.

source_suffix = {
        '.rst': 'restructuredtext',
        '.md': 'markdown'
}

[pbilling]

I used this web tool to validate my diagrams, so I'm confident it's not a syntax issue.

[pbilling]

I created a new page, specifically to test mermaid diagrams ("test-mermaid.md") and copy pasted one of the examples from https://github.com/mgaitan/sphinxcontrib-mermaid and it doesn't render. This indicates it's some issue with the sphinx/mermaid install or config.

    sequenceDiagram
      participant Alice
      participant Bob
      Alice->John: Hello John, how are you?

[pbilling]

New version of sphinxcontrib-mermaid was released 2 weeks ago: I'm going to try rolling back to the previous version.

UPDATE: No change. And I can see from build logs that packages are being installed successfully.

[pbilling]

Tried an example sequence diagram straight from the mermaid docs and it still just renders as text:

sequenceDiagram
    Alice->>John: Hello John, how are you?
    John-->>Alice: Great!
    Alice-)John: See you later!

[pbilling]

I'm looking closer at the readthedocs page for sphinxcontrib-mermaid and it doesn't look like the diagrams are rendering there either, so maybe this is a broader issue with the extension.

[pbilling]

This is a known issue, documented here: https://github.com/mgaitan/sphinxcontrib-mermaid/issues/110.

I rolled back the mermaid version as a temporary fix, until a new release is issued.

Line added to conf.py in https://github.com/StanfordBioinformatics/trellis-docs/commit/c1f42c450cc10bad79544497a4e6459b3e8f8fe6:

mermaid_version = "9.4.0"