# Simple diagrams in docs

**URL:** <https://discourse.julialang.org/t/simple-diagrams-in-docs/131884>\
**Category:** Tooling\
**Tags:** question, documenterjl, diagrams\
**Created:** [August 27, 2025, 1:21pm UTC](https://discourse.julialang.org/t/simple-diagrams-in-docs/131884 "2025-08-27T13:21:48Z")\
**Posts on this page:** 8\
**Page:** 1

<div class="post-metadata">

**Author:** ![Tamas\_Papp](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/tamas_papp/32/25949_2.png) [@Tamas\_Papp](https://discourse.julialang.org/u/Tamas_Papp)\
**Post date:** [August 27, 2025, 1:21pm UTC](https://discourse.julialang.org/t/simple-diagrams-in-docs/131884/1 "2025-08-27T13:21:48Z")

</div>

I would like to include a simple diagram (= boxes connected by arrows) in the docs of a Julia package, generated by Documenter.jl as usual.

I am not sure what my best option is.

I can just write it in whatever markup I like, render it on my machine to an SVG file and include it as an image. Pro: robust, no hassle. Cons: need to remember to regenerate and commit if updated.

I have seen DocumenterDiagrams.jl, powered by Kroki.jl. But currently [kroki.io](http://kroki.io) is down, and I would not want to call a web service each time the page is viewed.

Is there an in-Julia solution for rendering diagrams?

---

<div class="post-metadata">

**Author:** ![langestefan](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/langestefan/32/207923_2.png) [@langestefan](https://discourse.julialang.org/u/langestefan)\
**Post date:** [August 27, 2025, 1:26pm UTC](https://discourse.julialang.org/t/simple-diagrams-in-docs/131884/2 "2025-08-27T13:26:09Z")

</div>

For simple diagrams I like using mermaid: [Creating diagrams - GitHub Docs](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams)

and the plugin:

> **[GitHub - JuliaDocs/DocumenterMermaid.jl: Mermaid.js diagram intergration for Documenter.jl](https://github.com/JuliaDocs/DocumenterMermaid.jl)**
>
> Mermaid.js diagram intergration for Documenter.jl

---

<div class="post-metadata">

**Author:** ![baggepinnen](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/baggepinnen/32/693_2.png) [@baggepinnen](https://discourse.julialang.org/u/baggepinnen)\
**Post date:** [August 27, 2025, 1:33pm UTC](https://discourse.julialang.org/t/simple-diagrams-in-docs/131884/3 "2025-08-27T13:33:43Z")

</div>

I use [https://asciiflow.com/](https://asciiflow.com/) all the time, these have the nice property that you can copy-paste them everywhere, on slack, discourse, dostrings, documenter, email, you name it.

 ![image](https://global.discourse-cdn.com/julialang/original/3X/f/b/fb90e4aaa279dadcacc9e47fd31ae42ab41fe68b.png)

Here are a few examples rendered by Documenter

> **[Creating Systems · ControlSystems.jl](https://juliacontrol.github.io/ControlSystems.jl/dev/man/creating_systems/#From-block-diagrams-to-code)**
>
> Documentation for ControlSystems.jl.

---

<div class="post-metadata">

**Author:** ![jules](https://avatars.discourse-cdn.com/v4/letter/j/41988e/32.png) [@jules](https://discourse.julialang.org/u/jules)\
**Post date:** [August 27, 2025, 3:47pm UTC](https://discourse.julialang.org/t/simple-diagrams-in-docs/131884/4 "2025-08-27T15:47:50Z")

</div>

I’ve added a simple graphviz block in the Makie docs which should work with any Documenter based system

> <https://github.com/MakieOrg/Makie.jl/blob/master/docs/graphviz_block.jl>

used here for example

> <https://github.com/MakieOrg/Makie.jl/blob/0863e546aeb401a3041dbba9b633c047ac96341b/docs/src/explanations/architecture.md?plain=1#L51-L77>

---

<div class="post-metadata">

**Author:** ![langestefan](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/langestefan/32/207923_2.png) [@langestefan](https://discourse.julialang.org/u/langestefan)\
**Post date:** [August 27, 2025, 4:18pm UTC](https://discourse.julialang.org/t/simple-diagrams-in-docs/131884/5 "2025-08-27T16:18:01Z")

</div>

that option does not seem to work with darkmode?

 ![image](https://global.discourse-cdn.com/julialang/original/3X/4/f/4ffcb04367645c69371123643e9315b0c3820602.png)

---

<div class="post-metadata">

**Author:** ![jules](https://avatars.discourse-cdn.com/v4/letter/j/41988e/32.png) [@jules](https://discourse.julialang.org/u/jules)\
**Post date:** [August 27, 2025, 6:40pm UTC](https://discourse.julialang.org/t/simple-diagrams-in-docs/131884/6 "2025-08-27T18:40:21Z")

</div>

I didn’t pay attention to that at all, maybe one could hack something together to export twice with different color schemes

---

<div class="post-metadata">

**Author:** ![asinghvi17](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/asinghvi17/32/8272_2.png) [@asinghvi17](https://discourse.julialang.org/u/asinghvi17)\
**Post date:** [August 27, 2025, 7:17pm UTC](https://discourse.julialang.org/t/simple-diagrams-in-docs/131884/7 "2025-08-27T19:17:23Z")

</div>

DocumenterVitepress will already support this (but only for PNGs and JPGs at the moment):

> <https://github.com/LuxDL/DocumenterVitepress.jl/blob/fed5b1364dabb2f0d10de92b5068c170c30b0e8f/src/writer.jl#L850-L861>

although I should probably rewrite that code to be more reasonable…

---

<div class="post-metadata">

**Author:** ![Tamas\_Papp](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/tamas_papp/32/25949_2.png) [@Tamas\_Papp](https://discourse.julialang.org/u/Tamas_Papp)\
**Post date:** [August 28, 2025, 11:32am UTC](https://discourse.julialang.org/t/simple-diagrams-in-docs/131884/8 "2025-08-28T11:32:47Z")

</div>

> [@baggepinnen](#):
>
> I use [https://asciiflow.com/](https://asciiflow.com/) all the time, these have the nice property that you can copy-paste them everywhere, on slack, discourse, dostrings, documenter, email, you name it.

Out of the various great suggestions, this is the closest to my heart, so I am marking it as the solution.

I love this approach since it is just text in a ````` block, requires absolutely no tooling whatsoever to render, is completely future-proof, and there are various Emacs modes doing this too, eg [uniline](https://github.com/tbanel/uniline). Thanks!