GitHub now supports MermaidJS

GitHub now supports MermaidJS

[dave....-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org]

[-- Attachment #1.1: Type: text/plain, Size: 3455 bytes --]

 

Hi all,

Some food for thought on simple code block namespaces.

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

I’m the main author of KeenWrite (see screenshots 
<https://github.com/DaveJarvis/keenwrite/blob/master/docs/screenshots.md>), 
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 
<https://github.com/mermaid-js/mermaid/issues/2485>. This implies that 
typesetting Mermaid documents 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 
<https://talk.commonmark.org/t/mermaid-generation-of-diagrams-and-flowcharts-from-text-in-a-similar-manner-as-markdown/1882> 
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 
<https://pdfs.semanticscholar.org/7d75/49b737fd1d85bdaee016681e8915fea81ad9.pdf>), 
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.

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/6a978c09-0b8d-4199-862a-0a0b78955a41n%40googlegroups.com.

[-- Attachment #1.2: Type: text/html, Size: 4226 bytes --]

Re: GitHub now supports MermaidJS

[Albert Krewinkel]

"dave....-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org" <dave.jarvis-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> writes:

> Some food for thought on simple code block namespaces.
>
> Re: https://github.com/github/markup/issues/533
>
> [...] It's encouraging to see that
> Mermaid diagrams are being supported in GitHub.

I'm not sure I understand: The linked issue was closed with the author
being referred to GitHub support. Is Mermaid actually supported on
GitHub?

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

I believe that this is mostly out-of-scope for pandoc. But the
`diagram-` prefix could be implemented in the `diagram-generator` Lua
filter available here:
https://github.com/pandoc/lua-filters/tree/master/diagram-generator
A PR would be very welcome.

Thanks for bringing this up.

Cheers,
Albert

-- 
Albert Krewinkel
GPG: 8eed e3e2 e8c5 6f18 81fe  e836 388d c0b2 1f63 1124

Re: GitHub now supports MermaidJS

[dave....-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org]

[-- Attachment #1.1: Type: text/plain, Size: 1325 bytes --]

There's a bigger issue here that isn't about whether pandoc supports Kroki 
diagrams.

We're seeing a small-scale repeat of Browser Wars regarding *de facto* 
standards being ushered in without due process, which inevitably leads to 
splintering and incompatibilities. That was my main point, sorry that I did 
not state it directly.

To be clear, I think it'd be worthwhile to have a discussion about 
introducing simple namespaces regarding diagrams, syntax highlighting, and 
other possible ways to mark up diagrams. Without such a discussion, we'll 
see proliferation of Markdown documents that are specific to different 
implementations.

Or maybe having different flavours of Markdown is fine and any software 
that wants to support Markdown can optionally support as many flavours is 
people request: GitHub Markdown, GitLab Markdown, Pandoc Markdown, 
KeenWrite Markdown, Markdown-Writer-FX Markdown, etc.

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/414214a7-8d59-49ca-aefd-e617130b6d7en%40googlegroups.com.

[-- Attachment #1.2: Type: text/html, Size: 1706 bytes --]