Mermaid in asciidoc using the standard [mermaid] block

[davinkevin]

Select Topic Area

Product Feedback

Body

Hello 👋

This issue is related to asciidoctor/asciidoctor-intellij-plugin#1463.

In GitHub, if we want to read, in the online file viewer, an asciidoc file, we have to use the [source, mermaid] block.
However, in other popular tools (IntelliJ, GitLab…), the block to declare a diagram is just [mermaid].

Would it be possible to match the same as IntelliJ because we currently have to choose between rendering in the UI or in our IDEA, which is a bit painful 😅.

Thank you

Kevin

[gesinn-it-gea]

Same here. Would be awesome if GH could support both syntax variants.

[RapGhost901]

Absolutely

[ahus1]

The standard in the AsciiDoc ecosystem for diagrams is the asciidoctor-diagram which provides for each diagram type a block as described above.

The [source] block is limited to printing source code in the output, and it is defined in the AsciiDoc docs as such.

Due to that, the behavior GitHub shows here is very atypical to the AsciiDoc ecosystem.

[janhkrueger]

Would like to see a change here also. I use asciidoc and right know I need to choose if I want to get mermaids properly rendered in the editor or on github which does simply not feel right.

[ixti]

That would definitely be awesome!

[msche]

I experienced the same issue and came up with the following patch:

ifdef::env-github[]
:MERMAID: source, mermaid
endif::[]
ifndef::env-github[]
:MERMAID: mermaid
endif::[]

[{MERMAID}]
....
    C4Context
      title System Context diagram for Internet Banking System
      Enterprise_Boundary(b0, "BankBoundary0") {
        Person(customerA, "Banking Customer A", "A customer of the bank, with personal bank accounts.")
        Person(customerB, "Banking Customer B")
        Person_Ext(customerC, "Banking Customer C", "desc")

        Person(customerD, "Banking Customer D", "A customer of the bank, <br/> with personal bank accounts.")

        System(SystemAA, "Internet Banking System", "Allows customers to view information about their bank accounts, and make payments.")

        Enterprise_Boundary(b1, "BankBoundary") {

          SystemDb_Ext(SystemE, "Mainframe Banking System", "Stores all of the core banking information about customers, accounts, transactions, etc.")

          System_Boundary(b2, "BankBoundary2") {
            System(SystemA, "Banking System A")
            System(SystemB, "Banking System B", "A system of the bank, with personal bank accounts. next line.")
          }

          System_Ext(SystemC, "E-mail system", "The internal Microsoft Exchange e-mail system.")
          SystemDb(SystemD, "Banking System D Database", "A system of the bank, with personal bank accounts.")

          Boundary(b3, "BankBoundary3", "boundary") {
            SystemQueue(SystemF, "Banking System F Queue", "A system of the bank.")
            SystemQueue_Ext(SystemG, "Banking System G Queue", "A system of the bank, with personal bank accounts.")
          }
        }
      }

      BiRel(customerA, SystemAA, "Uses")
      BiRel(SystemAA, SystemE, "Uses")
      Rel(SystemAA, SystemC, "Sends e-mails", "SMTP")
      Rel(SystemC, customerA, "Sends e-mails to")

      UpdateElementStyle(customerA, $fontColor="red", $bgColor="grey", $borderColor="red")
      UpdateRelStyle(customerA, SystemAA, $textColor="blue", $lineColor="blue", $offsetX="5")
      UpdateRelStyle(SystemAA, SystemE, $textColor="blue", $lineColor="blue", $offsetY="-10")
      UpdateRelStyle(SystemAA, SystemC, $textColor="blue", $lineColor="blue", $offsetY="-40", $offsetX="-50")
      UpdateRelStyle(SystemC, customerA, $textColor="red", $lineColor="red", $offsetX="-50", $offsetY="20")

      UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")
....

which renders the image properly in InteliJ and GitHub.

[dverbru]

I appreciate that seem to be a workaround, yet I think that GitHub has to align with the standard way to avoid this pitfall to many people.

[Koriit]

This is necessary if we want to improve reviewer experience in GitHub.

[Koriit]

As a workaround I'm using chrome extension to render my mermaid diagrams:
https://chrome.google.com/webstore/detail/mermaid-previewer/oidjnlhbegipkcklbdfnbkikplpghfdl

[TeaDrinkingProgrammer]

+1