MacDownApp / macdown

Open source Markdown editor for macOS.
https://macdown.uranusjr.com/
9.43k stars 1.09k forks source link

Don't overload code block syntax for graphviz and mermaid #1129

Open cfilipov opened 4 years ago

cfilipov commented 4 years ago

I think that triple back quote should always render a code block and a different syntax should be used for code that should be interpreted/executed/rendered.

I found this comment in #625 already brought up my concern but I have not seen it fully addressed in that thread or others. I'm late to the party since this is already implemented but wanted share my thoughts just in case anyone likes this idea.

Instead of extending markdown with even more custom syntax you can take advantage of the fact that markdown supports embedding HTML which gets passed to the rendered output verbatim. I propose using the <script> tag with the type set to the mime type for format to be rendered. In macdown preview this can be rendered as you would expect, but if you open the same markdown file elsewhere this will gracefully fail because the browser will ignore that element.

Example:

# Embedded rendered code example

The following should render a code block, NOT a graph:

```dot
digraph D {
  A -> B
}
```

The following will render a graph in MacDown, 
but will not render anything in other markdown environments 
(this could be considered a disadvantage by some):

<script type="graphviz">
digraph D {
  A -> B
}
</script>

Since neither graphviz or mermaid seem to have an official mime type theirs would be text/vnd.graphviz ands text/vnd.mermaid respectively. Or you could just do away with formalities and just use graphviz and mermaid to keep it shorter.

Semantically, this is similar to how the script tag is typically used, interpreting its contents using an engine defined by the type attribute, we're just extending the number of engines (and there have been attempts in the past to do this with other languages, most notably VBScript). I think this provides a nice way to handle any other situation where you have a code block that needs to be run at render time.

FranklinYu commented 4 years ago

I guess this would be a breaking change? I guess we forgot to check this when the Pull Request was merged. It was two years ago after all… Can’t really recall what happened that time.

cfilipov commented 4 years ago

I didn't realize how old the issue that issue was when I quoted it. I don't think this is a "breaking" change depending on how you define that. If this were to be implemented then code fences would go back to rendering the code (as one would expect) and the <script> tag would be an added feature.

FranklinYu commented 4 years ago

I don't think this is a "breaking" change depending on how you define that.

I have to be conservative about this. You can help by inviting others to vote for your idea, so that I can at least have some evidence to deal with possible complaint.