☕ Coffee-brain idea: Mermaid diagrams for Rails Docs

This is only a half-baked idea, so apologies for that, hopefully can find time to flesh this out more – hoping this might inspire some folks interested in contributing here.


There are a few places we have embedded images for diagrams to explain certain parts of the Rails framework. For example, you can see this crufty png of the belongs_to association in AR.

Diagrams are great for explaining complex information succinctly.

The problem here is that maintaining these images is nearly impossible, do you have the right image editor to create that green gradient? They are also not very accessible.


mermaid.js is a very popular tool for building diagrams in code. By writing code to generate the diagram, you are creating an artifact which is maintainable (committed to git), and accessible (it’s just text underneath).


Starting with the guides, because that seems to be the most common place for diagrams.

There is a markdown renderer that handles code blocks here:

I believe since the language parameter is whatever you put after the fences (\```), it could be anything, like “mermaid”. We should then be able to handle the code in that case, passing it to the mermaid-cli, and output an svg that we can link to in the generated html.

This method block_code is designed to take the parsed markdown block from Redcarpet and format it with Rouge for syntax highlighting, but seems like the best place to repurpose for also handling diagrams.


Since RDoc also parses code blocks and provides an api for them, I think there might be a way to get diagrams into the API docs as well – but I haven’t thought about it much.


Again, this is just a very early idea, and I haven’t tried building a PoC or anything. Just putting it out there to see what folks think.