1. 146
  1.  

  2. 34

    I am super excited by this. I’m looking forward to combining this with ARCHITECTURE.md files to make some kick-ass documentation for our company’s devs for our repo(s).

    1. 1

      Prior discussion on above link.

      Adding focused pandas dev doc onboarding had a high impact on adoption (not just contribution) when we added it in 2012. Those have evolved since; not offering as an idealized example, just sharing after recent reflections on the past decade to elaborate on my previous comment re: the audience over the architecture.

    2. 29

      Re: https://github.com/github/markup/issues/533

      I’m the main author of KeenWrite (see screenshots), a type of desktop Markdown editor that supports diagrams. It’s encouraging to see that Mermaid diagrams are being supported in GitHub. There are a few drawbacks on the syntax and implications of using MermaidJS.

      First, only browser-based SVG renderers can correctly parse Mermaid diagrams. I’ve tested Apache Batik, svgSalamander, resvg, rsvg-convert, svglib, CairoSVG, ConTeXt, and QtSVG. See issue 2485. This implies that typesetting Mermaid diagrams is not currently possible. In effect, by including Mermaid diagrams, many documents will be restricted to web-based output, excluding the possibility of producing PDF documents based on GitHub markdown documents (for the foreseeable future).

      Second, there are numerous text-to-diagram facilities available beyond Mermaid. The server at https://kroki.io/ supports Mermaid, PlantUML, Graphviz, byte fields, and many more. While including MermaidJS is a great step forward, supporting Kroki diagrams would allow a much greater variety. (Most diagrams produced in MermaidJS can also be crafted in Graphviz, albeit with less terse syntax.)

      Third, see the CommonMark discussion thread referring to a syntax for diagrams. It’s unfortunate that a standard “namespace” concept was not proposed.

      Fourth, KeenWrite integrates Kroki. To do so, it uses a variation on the syntax:

      ``` diagram-mermaid
      ```
      
      ``` diagram-graphviz
      ```
      
      ``` diagram-plantuml
      ```
      

      The diagram- prefix tells KeenWrite that the content is a diagram. The prefix is necessary to allow using any diagram supported by a Kroki server without having to hard-code the supported diagram type within KeenWrite. Otherwise, there is no simple way to allow a user to mark up a code block with their own text style that may coincide with an existing diagram type name.

      Fifth, if ever someone wants to invent a programming language named Mermaid (see MeLa), then it precludes the possibility of using the following de facto syntax highlighting:

      ``` mermaid
      ```
      

      My feature request is to add support for Kroki and the diagram- prefix syntax. That is:

      ``` diagram-mermaid
      ```
      

      And deprecate the following syntax:

      ``` mermaid
      ```
      

      And, later, introduce the language- prefix for defining code blocks that highlight syntax. That is, further deprecate:

      ``` java
      ```
      

      With the following:

      ``` language-java
      ```
      

      That would provide a “namespace” of sorts to avoid naming conflicts in the future.

      1. 10

        I don’t think moving the existing stuff to language- is necessary, however I agree that diagram-mermaid is a better option – especially if one wants syntax highlighting for the syntax of the Mermaid diagramming language, to describe how to write such diagrams.

        1. 1

          First, only browser-based SVG renderers can correctly parse Mermaid diagrams. I’ve tested Apache Batik, svgSalamander, resvg, rsvg-convert, svglib, CairoSVG, ConTeXt, and QtSVG. See issue 2485

          Do you mean the output of mermaid.js? Besides that these SVG parsers should be fixed if they are broken and maybe mermaid.js could get a workaround, surely a typset system could read the mermaid syntax directly and not the output of a for-web implementation of it?

          1. 2

            If you look at the issue, there’s a fairly extensive list of renderers affected. This suggests that the core problem is that mermaid uses some feature(s) which are not widely supported.

            1. 1

              Besides that these SVG parsers should be fixed if they are broken

              Not sure if they are broken per se. The EchoSVG project aims to support custom properties, which would give it the ability to render Mermaid diagrams. From that thread, you can see supporting SVG diagrams that use custom properties is no small effort. Multiply that effort by all the renderers listed and we’re probably looking at around ten years’ worth of developer hours.

              surely a typset system could read the mermaid syntax directly and not the output of a for-web implementation of it

              Yes. It’s not for free, though. Graphviz generates graphs on par with the complexity of Mermaid graphs and its output can be rendered with all software libraries I tried. IMO, changing Mermaid to avoid custom properties would take far less effort than developing custom property renderers at least eight times over.

              1. 2

                IMO, changing Mermaid to avoid custom properties would take far less effort than developing custom property renderers at least eight times over.

                Sure, but as I said the ideal would be neither of those, but to just typeset the mermaid syntax directly and not rely on the JS or the SVG at all.

          2. 16

            The diagramming support is one of the things I miss most after moving from gitlab to github.

            1. 8

              Interesting! Didn’t know GitLab flavored Markdown supported that (and more).

              https://docs.gitlab.com/ee/user/markdown.html#diagrams-and-flowcharts

              1. 10

                Gitea also supports mermaid diagrams.

              2. 5

                Curious… why bother moving forges from open-core to closed-source?

                1. 3

                  GitHub has a lot more social features. I’ve had a clue of projects on GitHub get issues and pull request with no marketing. So people are finding and using things.

                  I’ve considered if I should set up mirrors of my GitLab projects on GitHub for the marketing effects.

                  1. 2

                    The social features are one of my biggest turn-offs, but you’re not the first to voice that opinion.

                    1. 5

                      I pretend that I don’t care about the social features. I really like that you can follow releases and the reaction option is kinda nice (so people can voice their support on new releases, without any comment noise).

                      I don’t follow anyone, because that’s just adding a ton of stuff into my feed. But honestly it makes me happy when somebody does give me a “star” and I think it’s ok to have this vague indicator of credibility for projects.

                      But I do actually search on github first when I’m looking for some kind of software I don’t find directly by using DDG. So the network effect is definitely there. Same goes for inter-project linking of issues or commits. And I won’t be surprised if moving my crates.io source to gitlab would decrease the amount of interaction as much as moving it to my private gogs/gitea instance.

                    2. 2

                      I’m curious what the social features are? I’ve used GitHub since it came out, but have never specifically noticed this

                      1. 2

                        follows. watches. stars. networks. there might be more. Github has been on my radar since it came up and these have long annoyed me. I think one of their early slogans was “social coding” and it was irritating then. Some people really like it though.

                    3. 3

                      For me it was largely about switching of culture of my work, shortly followed by me switching companies.

                      Personally if I were to start again I think I would utilize gitlab again. While occasionally their solutions lack the polish and simplicity of github, The “whole package” of their offerings is really nice. The only consistent downside is performance of certain UI elements.

                  2. 8

                    Really a shame they chose to support a new diagram language like Mermaid rather than one that has been around for 30 years, is widely used, and extremely flexible? Especially since is already a massive set of Graphviz files on Github. A simple search finds approximately 2,441,463 Graphviz files on Github (Source: https://github.com/search?q=extension%3Agv&type=Code&ref=advsearch&l=&l= and https://github.com/search?q=extension%3Adot&type=Code&ref=advsearch&l=&l=). A Github search for Mermaid on turns up only 7,846 files (https://github.com/search?q=extension%3Ammd&type=Code&ref=advsearch&l=&l=), making extremely unpopular by comparison. Why would Github ignore Graphviz and choose to support Mermaid instead?

                    Perhaps they looked at the number of Graphviz files in existence and realized that due to it’s popularity, they’d have to have a lot more infrastructure in place and the cost would be much greater? For example, if you figured rendering a diagram cost 1 cent (just as an example, I have no idea how much it costs). Rendering their library of Mermaid would only cost them about $78. Whereas Graphviz would end up costing them $24,414.63. Perhaps there are other technical constraints here I am not aware of? Maybe they’ve already got good infrastructure in place for JS libraries, and therefore Mermaid is an easier implementation.

                    1. 9

                      To be fair, mermaid seems to be more of a format to be used inline in a markdown file, so searching for dedicated .mmd files won’t be a good indicator of its popularity.

                      (I don’t know anything much about either mermaid or viz, and don’t care whichever github supports)

                      1. 4

                        Graphviz is more akin to SVG than Mermaid. It’s an image format, not a text description language.

                        1. 4

                          I assume by graphciz they mean the dot format, which is meant for hand authoring. Though it seems like a different use case than mermaid.

                        2. 1

                          I mean, no reason we can’t have both in the future?

                          I say this as someone who only uses Graphviz, but I don’t think “older language/more files of it exist” is a fair comparison of which is more popular today. And I certainly wouldn’t praise Graphviz for being extremely flexible – AFAIK you resolve positioning errors (which are common) by cleverly adding invisible edges, or partitioning cleverly into subgraphs, or even by specifying coordinates for every single node, which is hell.

                        3. 6

                          They’re really getting onto the long … tail … of features now ;)

                          1. 4

                            This is great! I’ve been working around the lack of this feature for years.

                            1. 4

                              now we just need mermaid in Rust docs. Mermaid everywhere.

                              1. 3

                                perennial request for corporate tag

                                1. 2

                                  Hmm. Seems useful, but also I think I’d rather use SVG for more portability? But then, this seems more accessible.

                                  1. 2

                                    I don’t use GitHub but this is the first time I’ve heard of Mermaid and honestly I wish I knew about this a few years ago.

                                    1. 2

                                      This is fantastic! I use this a lot in Markdown on GitLab, which already supports this. It’s great for design documents.

                                      1. 2

                                        The big advantage of Mermaid is that it’s done completely in the browser, so the cost is minimal for GitHub. PlantUML, Graphviz, etc would need a server side rendering component.

                                        Unfortunately Mermaid is not quite as mature as PlantUML and some stuff doesn’t work that well. It really isn’t good enough for publication-quality output. Hopefully this will bring renewed interest and it can improve!

                                        1. 2

                                          This looks useful!

                                          1. 1

                                            I assumed this was a new diagram type. Turns out to just be a politically correct and acceptable name for much of poor old UML.

                                            1. -2

                                              Finally something useful came out of Github.

                                              1. 1

                                                Almost all the work on Mermaid came from Knut Sveidqvist, a web developer working in his spare time.

                                                1. 1

                                                  I was joking. I love Mermaid to death, using it for all kind of things, including:

                                                  • teaching
                                                  • documentation

                                                  Thanks Knut if you read this!