Discussion: The way Typora extends GFM

[vassudanagunta]

I think that any extensions that Typora makes to GFM/CommonMark should be done in a way that degrades gracefully when viewed in or processed by another GFM compatible or even standard Markdown tool. I believe GFM follows this rule in the ways it extends CommonMark. The way Typora uses fenced code blocks for diagrams is a beautiful example of this (nice job!). See how this Mermaid diagram block degrades nicely right here on GitHub:

graph LR
A[Hard edge] -->B(Round edge)
B --> C{Decision}
C -->|One| D[Result one]
C -->|Two| E[Result two]

While the diagram isn't rendered, it will survive being edited by another markdown editor undamaged, because fenced code blocks aren't supposed to be touched. I'm not so sure about the approach for Math blocks:

$$ \mathbf{V}_1 \times \mathbf{V}_2 = \begin{vmatrix} \mathbf{i} & \mathbf{j} & \mathbf{k} \ \frac{\partial X}{\partial u} & \frac{\partial Y}{\partial u} & 0 \ \frac{\partial X}{\partial v} & \frac{\partial Y}{\partial v} & 0 \ \end{vmatrix} $$

Unlike the mermaid diagram code, the math block code is depicted neither as a block nor as code. It actually looks even worse if you try it in a Markdown file on GitHub (rather than in a GitHub comment). Since it exists outside the protection of a code block, other tools my end up altering it, just as Typora often tries to normalize the Markdown it writes (e.g. #1188 and #1189).

See also #1202, a recent suggested change for the TOC marker.

Thoughts?

/cc @Crissov, @KirkMunro, #369

[Crissov]

Commonmark still has not adopted rules for how syntax extensions should work. You are right, of course, that using the info string of fenced blocks provides a clean path for additions – unless you need to put source code and output into the same document. For this case, I have proposed to treat backtick and tilde blocks differently.

[KirkMunro]

@Crissov I don't believe treating backtick and tilde blocks differently is an option. If I want to create a fenced code block that internally contains markdown, where I am using another fenced code block, I need two different fenced code blocks in order to be able to do that. The following fenced code block is written with tildes at the top level.

Here is how you write a fenced code block in markdown:

```PowerShell
Get-Service wuauserv | Stop-Service
```

If suddenly the two different block definitions are treated differently, that could break existing markdown.

@vassudanagunta Regardng this issue, I'm a little confused, because this isn't a Typora problem as far as I can tell...it's a problem with the CommonMark standard, because they haven't decided on a common syntax for extensions. Unlike the markdown prettification issues that have thankfully been getting fixed, Typora is just supporting certain markdown extensions, some of which have been designed with other locations where markdown is used in mind, and others not.

I can't recall where I saw the syntax (somewhere on CommonMark, in the forums, I think), but I've taken a liking to this syntax for a common extension model to trigger special rendering of the contents of the block:

::: extension arguments
content to be rendered with extension
:::

Following that syntax, mermaid diagrams could be rewritten as follows:

::: graph LR
A[Hard edge] -->B(Round edge)
B --> C{Decision}
C -->|One| D[Result one]
C -->|Two| E[Result two]
:::

Something similar could be done for LaTeX as well. The challenge with this syntax is creating an extension that supports inline use within a paragraph. Colon is obviously a character that has wide use in markdown documents, so simply surrounding something with single colons won't do (e.g. :content to be rendered with extension:). GitHub already overloads that syntax for emojis. Plus that syntax does not allow me to specify what the extension is, nor what arguments I want passed to that extension. Perhaps inline use would be defined more like this: ::extension arguments:content to be rendered with extension:: (intentionally using double-colon on the outside, with a single colon in the middle between the extension details and the extension contents, and strict rules about extension naming and arguments (alpha-numeric only, no symbols) to avoid breaking existing markdown).

At any rate, while the CommonMark standard seems focused on getting version 1 defined before they focus on extensions, given how long it is taking to get version 1 of the standard defined, I think at least deciding on an extension syntax would be beneficial to everyone so that we can get out of the situation we're in with $$ for one extension, and fenced code blocks for another. Simply deciding on the enclosure syntax for extensions would give tool builders something more solid to work with, and existing extensions could maintain backwards compatibility while moving to a default extension enclosure syntax that makes identification of extensions, as well as rendering of their contents, something that is handled well everywhere.

[vassudanagunta]

@KirkMunro @Crissov

Sorry, my first sentence was ambiguous. I meant to say I think that any extensions that Typora makes to GFM/CommonMark should be done in a way that degrades gracefully when viewed in or processed by another GFM compatible or even standard Markdown tool. [EDIT: I just updated the desc above.]

Yes, this is not the place to discuss how GFM or CommonMark should support extensions. What I'm getting at is that Typora, obviously, isn't waiting for those standards to add support for the things that Typora is already supporting (e.g. diagrams). I just want Typora to do it in a way that plays nice with other GFM/CommonMark tools. For example GFM's extensions to CommonMark follow this principle (intentionally or not).

I definitely don't want Typora to try to solve the problem of the best way to support extensions. And if and when CommonMark figures it out, I hope Typora conforms. But until then, I think it fine if Typora uses the fenced code block approach that works fine but breaks in some rare corner cases of code blocks within code blocks. But is that even a problem?

```mermaid
graph LR
A[Hard edge] -->B(Round edge)
B --> C{Decision}
C -->|One| D[Result one]
C -->|Two| E[Result two]
```

[KirkMunro]

@vassudanagunta Thanks for clarifying. The enclosures for the math extension you reference in your post ($$) seem to be commonly used for math/TeX extensions in markdown -- not that I like that decision, I'm just pointing out that this didn't seem to be an extension that Typora made.

For that specific example, I wonder if Typora should allow users to choose the extension enclosure they want, like markdown-it-texmath does.

[vassudanagunta]

1282 is an example, I believe, of what Typora should not support.