search

microsoft / language-server-protocol

Defines a common protocol for language servers.
https://microsoft.github.io/language-server-protocol/
Creative Commons Attribution 4.0 International
11.28k stars 799 forks source link

Math support in Markdown #1538

Open azdavis opened 2 years ago

azdavis commented 2 years ago

Background

  1. GitHub, which is owned by Microsoft, recently added support for using $ and $$ to delimit math expressions in Markdown rendered on GitHub:

    Today we are pleased to announce that math expressions can be rendered in Markdown on GitHub using $$ as a delimiter for code blocks with math content or the $ delimiter for inline math expressions.

  2. GitHub states that the Markdown syntax that GitHub supports is called GitHub Flavored Markdown (GFM):

    GitHub Flavored Markdown, often shortened as GFM, is the dialect of Markdown that is currently supported for user content on GitHub.com and GitHub Enterprise.

  3. The LSP spec states that the Markdown syntax supported in MarkupContent is that very same GitHub Flavored Markdown:

    If the format is markdown the content should follow the GitHub Flavored Markdown Specification.

Expected behavior

Given the above, I expected to be able to use $ and $$ to render math in Markdown using LSP.

Actual behavior

However, when testing with VS Code, it doesn't work.

Notably, VS Code, also owned by Microsoft, also supports $ and $$ for math in Markdown, but apparently only in its Markdown doc preview feature.

Explanation

Digging deeper, it appears as though even though GitHub claims that GFM is the definition for Markdown on GitHub, the GFM spec hasn't been updated for a while, and doesn't mention the math rendering support. So, technically, LSP is correctly following the current GFM spec by not rendering math with dollar signs.

However, I'd like to start a discussion about whether this would be a desirable feature for LSP's Markdown. I think it'd be useful, as an example, if one could display things like big-O notation for documentation comments with proper math rendering.

Action to take

I see a few things we could do.

Update the GFM spec to talk about dollar sign math

This seems to be the most "correct" option, since GFM is supposed to be the definition of the Markdown supported by GitHub, yet there is currently a deviation between what the GFM spec states and what GitHub actually supports.

If we do this, then dollar sign math support would then enter LSP as well, since LSP states that the Markdown supported by LSP is GFM.

However, doing this would require convincing GitHub to update the GFM spec, which is not necessarily under the control of the LSP spec maintainers. (Though, as noted, both GitHub and LSP are owned by Microsoft.)

Support dollar sign math "on top" of GFM

This is what GitHub itself seems to be doing. We might choose to introduce a new flavor of MarkupContent called "GFM + dollar sign math Markdown" or something for backwards compatibility.

Do nothing

Keep the status quo, and don't support dollar sign math. But as noted, I at least would like support for this feature.

KamasamaK commented 2 years ago

Introducing "a new flavor of MarkupContent" would be the wrong approach to resolve this. There should simply be a way for MarkdownClientCapabilities to have the client declare support for rendering math in that way. But as you noted, it would probably need to be added to the GFM spec first, which is outside the scope of LSP, or noted that the capability exists outside of GFM.

azdavis commented 2 years ago

Opened a thread on GitHub Discussions: https://github.com/orgs/community/discussions/30605