Menu

Sphinx Markdown Mermaid Preprocessor

by Dorian on #Git, #gitlab, #markdown, #mermaid, #Python, #sphinx, #til,

Last year, we migrated all our companies documentation to markdown rendered via sphinx. Because of Gitlab and Typora we are a little bit spoiled and wanted to keep our good looking mermaid js graphs - needles to say, that this was not supported by sphinx.

Our solution to that was to use a (hacky) pre- and a postprocessing script in the continious integration.

The script goes through any markdown file and translates the markdown mermaid notation to a simple HTML mermaid notation.

sphinx-mermaid.py (Source)

from pathlib import Path
def mermaid(md):
    new_content = ""
    replacement_in_progress = False
    with open (md, 'r' ) as f:
        line = f.readline()
        while line:
            new_line = line
            if "```mermaid" in line:
                new_line = '<div class="mermaid">\n'
                replacement_in_progress = True
            elif "```" in line and replacement_in_progress:
                new_line = '</div>\n'
                replacement_in_progress = False
            new_content += new_line
            line = f.readline()
    f.close()
    with open (md, 'w' ) as f:
        f.write(new_content)
        f.close()
for md in Path("source").glob("**/*.md"):
    file_string = str(md.absolute())
    mermaid(file_string)

It can be used before the regular sphinx call.

⚠ The source of the markdown files will be changed permanently, so please use this only in context of disposable CI environments.