Enhancing Elixir Documentation with Mermaid Charts

Add beautiful Mermaid Charts to your Elixir Docs!

How to add Mermaid Charts to an Elixir App

A prerequisite is that you install the ex_doc package. Add it to your mix.exs but there’s no need to include it in the runtime, so take advantage of the various dependency options:

{:ex_doc, "~> 0.24.2", only: [:dev], runtime: false}
def project do
[
# ...
docs: [
before_closing_body_tag: fn
:html ->
"""
<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
<script>mermaid.initialize({startOnLoad: true})</script>
"""
_ -> ""
end
]
]
<script src="https://kit.fontawesome.com/xxxxxxx.js" crossorigin="anonymous"></script>
@moduledoc """
My documentation goes here...
<div class="mermaid">
graph TD;
classDef server fill:#D0B441,stroke:#AD9121,stroke-width:1px;
classDef topic fill:#B5ADDF,stroke:#312378,stroke-width:1px;
classDef db fill:#9E74BE,stroke:#4E1C74,stroke-width:1px;
T1(TopicA):::topic --> G1{{GenServerA}}:::server;
T1(TopicA):::topic --> G2{{GenServerB}}:::server;
G2{{GenServerB}}:::server --> T2(TopicB):::topic;
T2(TopicB):::topic ==> DB[("Storage#nbsp;")]:::db;
</div>
"""
@version "v1.2.3"
@moduledoc """
This is version #{@version} of the software.
"""
@things [%{type: :server, name: :alpha}, ...]@moduledoc """
Here's the chart:
<div class="mermaid">
#{SomeHelperModule.make_chart(@things)}
</div>
"""

Tips

Don’t forget semi-colons ;at the end of the lines! A lot of the Mermaid examples omit them because they are optional when line breaks are present, but ex_doc strips out newlines so the semi-colons are required! After; every; line; otherwise the chart generation will fail.

Database[("fa:fa-database Storage#nbsp;")]
<style>
.mermaid {width:300% !important}
</style>

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store