MacDownApp / MacDownApp/macdown

Don't overload code block syntax for graphviz and mermaid

Open
#1,129 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
Rich Text Format
Stars
9.8k
Forks
1.2k
PR merge metrics
No merged PRs in 30d

Description

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](https://github.com/MacDownApp/macdown/pull/625#issuecomment-238119135) 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 `` 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
}

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](https://eager.io/blog/a-brief-history-of-weird-scripting-languages/) 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.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

No files, tests, or entry points are named. Review the existing graphviz and mermaid rendering behavior and the linked discussion in #625; done would require an agreed syntax and a decided implementation path for MacDown preview.

Written by the indexing model from the issue text.

Assessment

Tech stack
markdown
Domain
desktop
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.