Oh, I've just remembered that there's also a separate work on updating the typeclasses diagram: #4325.
AFAIK, the work it that PR is based on the Mermaid tool. But it just for a record. I personally have no experience neither with Mermaid nor Latex so I have no preference on that.

I am in favor of Mermaid because Laika (which we use to render the site) will have built-in support for it in the near future. GitHub also renders Mermaid out-of-the-box.

• support mermaid diagram blocks Laika#331

Oh, I've just remembered that there's also a separate work on updating the typeclasses diagram: #4325. AFAIK, the work it that PR is based on the Mermaid tool. But it just for a record. I personally have no experience neither with Mermaid nor Latex so I have no preference on that.

@satorg Thanks! I just checked the PR you mentioned.

Honestly speaking, I think the current Mermaid based diagrams in that PR doesn't have a fancy view, especially when comparing them with the existing cats-infographic. One example is the third diagram of that PR: https://github.com/tsobako/cats/blob/patch-1/docs/typeclasses.md. If, after some tweak, the Mermaid based diagrams can have better views, I also have no preference. Actually, because of @armanbilge's explanation, I even prefer the Mermaid solution if the view of its output is good enough. I believe we shouldn't give up an existing good solution just because it is not the built-in.

@ShapelessCat thanks for your comments.

If, after some tweak, the Mermaid based diagrams can have better views

Can you describe in more detail how it can be improved? In fact, if you can comment on that PR it would be great. Thanks!

I believe we shouldn't give up an existing good solution just because it is not the built-in.

Sure, and thank you for all your effort you put into it – to me the rendered diagram you created looks way better comparing to what we have on the website published now. But I also like the idea of having all the docs gathered in one place because it makes easier to keep the docs up-to-date in the future.

@ShapelessCat thanks for your comments.

If, after some tweak, the Mermaid based diagrams can have better views

Can you describe in more detail how it can be improved? In fact, if you can comment on that PR it would be great. Thanks!

@armanbilge
What I mean is I'm not sure if Mermaid has the expressiveness to control details and improve the view.
I'd like to spend time on reading Mermaid document, and have a try.

One thing I think should be improved is the arrows in current #4325. I can see that currently almost all the arrows in #4325 are generated by specifying the from node and to node, and no control for details. This leads to all these arrows being curved arrows. It seems Mermaid doesn't try to generate straight line arrows automatically. Too many curved arrows are distractive, and they make the view messy. I think one of the root causes is no nodes layout detailed control in the current #4325 Mermaid source code. Before reading the Mermaid document, I'm not sure if Mermaid can do this. I'll have a try and I hope I can find a way to let Mermaid generate straight line arrows.

I copied the below diagram from #4325. You can see the curved arrows I mentioned, and you also can see why I said: when there are many nodes, too many curved arrows are distractive, and they make the view messy. Compare the below diagram with the corresponding part in cats-infographic can make things even clearer.

graph BT;

    classDef core fill:#BBBBFF,stroke-width:2px,stroke:#000;
    classDef coreImportant fill:#6666FF,stroke-width:2px,stroke:#000;

    subgraph core
        direction BT
        id25(UnorderedFoldable):::core;
        id26(UnorderedTraverse):::core;
        id27(Invariant):::core;
        id28(Foldable):::coreImportant;
        id29(Functor):::coreImportant;
        id30(Semigroupal):::core;
        id31(Contravariant):::core;
        id32(Reducible):::core;
        id33(Traverse):::coreImportant;
        id34(InvariantSemigroupal):::core;
        id35(ContravariantSemigroupal):::core;
        id36(NonEmptyTraverse):::core;
        id37(Distributive):::core;
        id38(Apply):::core;
        id39(InvariantMonoidal):::core;
        id40(CoflatMap):::core;
        id41(FlatMap):::core;
        id42(CommutativeApply):::core;
        id43(Applicative):::coreImportant;
        id44(ContravariantMonoidal):::core;
        id45(Comonad):::core;
        id46(CommutativeFlatMap):::core;
        id47(Monad):::coreImportant;
        id48(CommutativeApplicative):::core;
        id49(ApplicativeError):::core;
        id50(Bimonad):::core;
        id51(CommutativeMonad):::core;
        id52(MonadError):::core;
        id53(SemigroupK):::core;
        id56(NonEmptyAlternative):::core;
        id54(MonoidK):::core;
        id55(Alternative):::coreImportant;
         
        id26-->id25;
        id28-->id25;
        id29-->id27;
        id31-->id27;
        id32-->id28;
        id33-->id26;
        id33-->id28;
        id33-->id29;
        id34-->id27;
        id34-->id30;
        id35-->id31;
        id35-->id34;
        id36-->id32;
        id36-->id33;
        id38-->id29;
        id38-->id34;
        id39-->id34;
        id40-->id29;
        id37-->id29;
        id41-->id38;
        id42-->id38;
        id43-->id38;
        id43-->id39;
        id44-->id35;
        id44-->id39;
        id45-->id40;
        id46-->id41;
        id46-->id42;
        id47-->id41;
        id47-->id43;
        id48-->id42;
        id48-->id43;
        id49-->id43;
        id50-->id45;
        id50-->id47;
        id51-->id46;
        id51-->id47;
        id51-->id48;
        id52-->id47;
        id52-->id49;
        id56-->id43;
        id56-->id53;
        id55-->id43;
        id55-->id54;
        id55-->id56;
        id54-->id53;
    end

I close this issue, and I'll firstly try to contribute to #4325.