Baike.dev
All toolsOnline toolsAI codingTrendingOpen sourceNewsSubmit
Log in
< Back to tools
A

aquamarine

> 编程语言
Open source

Inline diagrams for rustdoc with mermaid.js

558 stars0 likes1 views
WebsiteGitHub

About

Inline diagrams for rustdoc with mermaid.js

Aquamarine

Compiler support: this crate requires rustc 1.38.0 or newer

Aquamarine is a procedural macro extension for rustdoc, that aims to improve the visual component of Rust documentation through use of the mermaid.js diagrams.

#[aquamarine] macro works through embedding the mermaid.js into the generated rustdoc HTML page, modifying the doc comment attributes.

To inline a diagram into the documentation, use the mermaid snippet in a doc-string:

rust
#[cfg_attr(doc, aquamarine::aquamarine)]
/// ```mermaid
/// graph LR
///     s([Source]) --> a[[aquamarine]]
///     r[[rustdoc]] --> f([Docs w/ Mermaid!])
///     subgraph rustc[Rust Compiler]
///     a -. inject mermaid.js .-> r
///     end
/// ```
pub fn example() {}

The diagram will appear in place of the mermaid code block, preserving all the comments around it. You can even add multiple diagrams!

To see it in action, go to the demo crate docs.rs page.

You can learn more about mermaid.js and what it can do in the mermaid's documentation MdBook

Dark-mode

Aquamarine will automatically select the dark theme as a default, if the current rustdoc theme is either ayu or dark.

You might need to reload the page to redraw the diagrams after changing the theme.

Custom themes

Theming is supported on per-diagram basis, through the mermaid's %%init%% attribute.

Note: custom theme will override the default theme

rust
/// ```mermaid
/// %%{init: {
///     'theme': 'base',
///     'themeVariables': {
///            'primaryColor': '#ffcccc', 
///            'edgeLabelBackground':'#ccccff', 
///            'tertiaryColor': '#fff0f0' }}}%%
/// graph TD
///      A(Diagram needs to be drawn) --> B{Does it have 'init' annotation?}
///      B -->|No| C(Apply default theme)
///      B -->|Yes| D(Apply customized theme)
/// ```

To learn more, see the Theming Section of the mermaid.js book

Separating diagrams from code

A diagram, or multiple, can be loaded from file to reduce clutter in the documentation comments.

rust
#[cfg_attr(doc, aquamarine::aquamarine)]
/// My diagram #1
/// include_mmd!("diagram1.mmd")
/// My diagram #2
/// include_mmd!("diagram2.mmd")
pub fn example_foad_from_file() {}

In the wild

Crates that use aquamarine in their documentation

  • google/autocxx
  • replicadse/senile
  • teloxide

and other

Issues· 0 open

View all issuesOpen on GitHub

No open issues yet, or sync has not completed.

> Tags

Rust

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026
UpdatedSep 17, 2026
Category编程语言
PricingOpen source

> Related tools

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言