The alternative is no diagram at all, which sucks for understanding, or linking to an image that's likely just a binary blob which is now a hard dependency on your markdown file too. Mermaid is a great fit, it's a text description of common graph types and it's meant to be read, written, and understood by humans in text form.