On: Include diagrams in your Markdown files with Merma...

[qbasic_forever]

Only the mermaid identifier is supported for triple backticks blocks, you can't put js and have it spit out script that executes in the browser.

[e12e → qbasic_forever]

I think op meant that we can:

   ```ruby
   # syntax highlighted as ruby
   a = 1 + 1
   ```

And:

   ```js
   // syntax highlighted as js
   a = 1 + 1
   ```

So maybe we should have something like a "bang" prefix to evaluate and inline/embed like:

   ```!ruby
   # evaluated 
 as ruby
   a = 1 + 1
   # renders 2 because of implicit return? 
   ```

[martinwoodward → e12e]

The idea of the bang syntax came up. https://talk.commonmark.org/t/mermaid-generation-of-diagrams...

But in the end went with simple. There will be a very limited subset that will render this way - executing raw code without the users permission in the browser just opens up too much attack surface area that we’d need a very compelling use case to do the security work necessary to make it protected (even if that was possible)

[mintplant → martinwoodward]

Alright, but how do I embed highlighted Mermaid source code in Markdown now?

[qbasic_forever → mintplant]

embed the HTML:

<pre><code> your mermaid code <span class="foo">with highlighted</span> sections </code></pre>

Use a tool like pygments to generate the highlighted HTML (assuming there even is highlighting for mermaid syntax).

What you're asking for is an uncommon edgecase that's not what people want in 99% of circumstances (instead they want the rendered chart). Markdown still gives you the HTML escape hatch so use it. Sure it's not pretty but it's no worse than if github didn't support highlighting mermaid source anyways.

If you don't want highlighting just put a fenced code block without the mermaid info string. It will render as unhighlighted code. IMHO that's what you'd want as a workaround to demo source like in a mermaid readme.

[mintplant → qbasic_forever]

> What you're asking for is an uncommon edgecase that's not what people want in 99% of circumstances

It's how it worked before this change, and how it works for every other language in Markdown. This is taking away functionality with no reasonable replacement and creating a special-case gotcha in the Markdown syntax (the same syntax could produce highlighted code or a rendered image depending on the language and what features any particular Markdown implementation supports), and it's not clear why this is necessary when something like ```!mermaid would work just as well to trigger rendering. It's unforced bad language design.

> Use a tool like pygments to generate the highlighted HTML

This requires hardcoding colors into the generated HTML, so the highlighting won't match the color theme of the context that the document is embedded in, breaking e.g. dark mode.

[e12e → martinwoodward]

I don't think github should (generally) render stuff in the browser (although I see that both "benign"[1] graphs and source code highlights, not to mention the somewhat simple translation from Markdown to html - probably could be done in the browser as js/wasm.

But for "markdown the language" having a standard syntax for embed/evaluate along with prettify/highlight would've been nice - effectively a standard markup for multi-language "notebooks"/literate programs (maybe we need a triplet: format, render/embed, transclude/literate programming).

Github could then opt-in to highlighting the N languages they do, and initially only try to render mermaid graphs. Then perhaps also graphviz graphs. Etc.

[1] I'm sure one could do some minor DOS at least with a 500 mb graph..

[mukundesh → e12e]

Would be good to copy from MkDocs Material

https://squidfunk.github.io/mkdocs-material/reference/code-b...

``` py hl_lines="2 3"

def bubble_sort(items):

    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

```

[tehbeard → qbasic_forever]

You missed the point, that being; isn't triple backticks meant for whitespace preserving, highlighted in certain cases source code? And not embedding other file types.

[qbasic_forever → tehbeard]

No there's not a formal requirement or spec for how markdown blocks are rendered. Even things like syntax highlighting are optional choices different renderers make (and even the whole idea of highlighting is not specified or defined, how do you define the grammer, etc?).

Some tools in the computational notebook space use markdown with fenced code blocks as blocks of executable code, see for example jupytext: https://github.com/mwouts/jupytext/blob/main/docs/formats.md or myst markdown: https://myst-parser.readthedocs.io/en/latest/syntax/syntax.h... or nbconvert: https://nbconvert.readthedocs.io/en/latest/

[dijit → qbasic_forever]

There is a formal spec (from github themselves) for how it’s rendered.

What’s debatable is what the spec does with the “info” section.

https://github.github.com/gfm/#fenced-code-blocks

[qbasic_forever → dijit]

Sure but there's no markdown spec. Markdown is purely a series of blog posts by John Gruber and a collection of different implementations. CommonMark is as close to as it's gotten to a formal spec, and even it says there is no requirement the info string (i.e. text like mermaid after backticks) be interpreted for specific rendering (or not rendering) of the content: https://spec.commonmark.org/0.28/#fenced-code-blocks

[acchow → qbasic_forever]

It's rendering style, not execution.

[reificator → qbasic_forever]

Which is the exact inconsistency under scrutiny here.

[qbasic_forever → reificator]

Markdown supports arbitrary HTML, you can do this:

    # Heading

    <script>
    const foo = 1 + 1;
    window.alert(`1 + 1 = ${foo}`);
    </script>

    Paragraphs of exposition.

In practice most markdown renderers will strip HTML or at least script tags as it is obviously a cross site security risk to allow github.com to serve user uploaded scripts without sanitization.

[reificator → qbasic_forever]

I think you're caught up on exactly the opposite of the complaint here. People aren't requesting JS execution, they have the various "notebook" solutions for that.

People are saying that triple backtick fenced code blocks are used to preserve whitespace and fixed width, usually with syntax highlighting as a bonus. That's the expected behavior.

However with the described mermaid support, it's taking a fenced code block with a mermaid tag and transforming it into a graph.

When inspecting the text content of a markdown file, there's no difference between a `javascript` tagged code block, a `haskell` tagged one, and a `mermaid` tagged one. But now when rendering, the mermaid one is special cased.

This is undesirable for multiple reasons, the most obvious being that it's now harder to write a README that displays mermaid syntax.

A good starting point would be either different syntax or a different tagging convention. For instance I think I saw `!mermaid` suggested, where the `!` would mean that the code should be interpreted instead of rendered as code.

I don't have a horse in the race of what this looks like, only that there should be a distinction between rendered and interpreted code blocks.

[qbasic_forever → reificator]

You're pushing a rock up hill--many markdown renderers natively support mermaid, plantUML, etc. using fenced code blocks.

If you explicitly want source code rendering don't add the mermaid tag to the block. There could be an argument that now you don't get syntax highlighting, but remember syntax highlighting itself is not part of any markdown spec and it differs wildly between implementations--there is no common grammar or spec for it even.

In all cases these are still valid markdown files and will pass through markdown processing, rendering, etc. systems without breaking them.

[reificator → qbasic_forever]

> You're pushing a rock up hill--many markdown renderers natively support mermaid, plantUML, etc. using fenced code blocks.

And yet Github's markdown support carries much more weight. Raising concerns at this point is a perfectly reasonable thing to do.