simple-mermaid

Simple Mermaid diagrams RustDoc integration

This crate provides a simple declarative macro to include mermaid diagrams in your rustdoc documentation. Lookup the great mermaid documentation for details on the diagram syntax.

Usage

1. Create your mermaid diagrams in their own files (usually with .mmd or .mermaid extension).
2. Call the [mermaid!] macro in a #[doc] attribute. Specify the route to the diagram file as a string literal. Note that the path is interpreted relative to the file where the macro is called, as it happens with the underlying include_str.
3. Done!

Alternatives

aquamarine

The aquamarine introduces a procedural macro that converts regular code blocks marked with the mermaid language tag. It also allows including the diagram from external files, but that comes with some limitations:

• Only one external diagram can be added to a single doc block.
• The external diagram will always appear at the end of the doc block.

Those limitations made aquamarine a non-option for me, since I strongly prefer leaving the diagrams in external files for several reasons: clutter, maintainability, IDE support, and, re-usability of the diagrams.

Besides, the declarative macro used in this crate should be easier on compile times. And it comes with no dependencies at all!

rsdoc

The rsdoc crate provides procedural macros to embed PlantUML and images in doc coments. It can be used with code-blocks (similar to aquamarine) or with external files (similar to this crate). So, in this case, for me it was just a matter of personal taste, both PlantUML and mermaid are fantastic opensource projects. But PlantUML is Java... and my plants always die (even a cactus I once had! How can a cactus die? The thing should not need water!).

Mermaid compatibility

The 0.1.x versions of this crate use mermaid v10.

The 0.2.x versions use mermaid v11.

Since updating mermaid might be a breaking change, any updates in the major version of mermaid used in this crate will always result in a bump in the first non-zero version digit.

Disclaimer

Neither this crate nor it's autor have any relation or affiliation with the mermaid project, other that being an user of this magnific library.

All the examples in this documentation have been extracted, verbatim or with minor updates, from the mermaid documentation.

License: MIT