☕ Coffee-brain idea: Mermaid diagrams for Rails Docs

rubyonrails-docs
1

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.

Problem

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.

Solution

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).

How

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.

RDoc

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.

Etc

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.

Thanks!

9 Likes
2

I landed on this wanting to do the same thing. Old post but not that old. I had another goal that we could build mermaid graphs separately instead of bogging down documentation with that kind of markup. Benefit is that VSCode/Intellij support .mermaid allowing you to preview your diagram while building it.

Put a couple of hours towards this, getting yard to play nice with a custom markdown renderer was not working so ultimately I decided to fork the gem and make a quick change. Should be fairly easy to keep current.

My quick edit:

      elsif File.file?(file)
            if file.split(".").last == "mermaid"
              "<div class=mermaid>#{File.read(file)}</div>"
            else
              link_include_file(file)
            end
      else

This allows you to easily embed the diagram in a comment using {include:file:diagram.mermaid}

To tie this together, you need to add mermaid.js to the templates/default/fulldoc/html/js and plug it in accordingly. Works like a charm.

  # Add a description here, lorem ipsum
  #
  # ### DIAGRAM
  #
  # {include:file:test.mermaid}
  #
  # @see http://example.com Description of URL

yields

CleanShot 2024-01-24 at 08.45.31
CleanShot 2024-01-24 at 08.45.311265×547 18.9 KB