Markdown extensions allow you to extend and enhance Visual Studio Code's built-in Markdown preview. This includes changing the look of the preview or adding support for new Markdown syntax.
- Github Markdown Mermaid Mod
- Does Github Support Mermaid
- Github Markdown Diagram
- Github Markdown Mermaids
While all Mermaid.js features should work out-of-the-box, Material for MkDocs will currently only adjust the fonts and colors for flow charts, class and state diagrams. Support for further diagram types will be added gradually. ↩ If you don't want to use the native integration, mkdocs-mermaid2-plugin might be a good alternative. However, note that this plugin cannot be used in conjunction.
Mermaid is a JavaScript based parsing engine that allows you to embed blocks of graph markup into a page. Markdown Monster supports two different approaches using either code block or HTML tag syntax to embed the mermaid blocks. @icon-warning Internal Preview Limitations. Markdownish syntax for generating flowcharts, sequence diagrams, class diagrams and gantt charts. Content delivery at its finest. Cdnjs is a free and open-source CDN. How to make GitHub Pages Markdown support mermaid diagram? How to type in multiple spaces in mermaid? Hot Network Questions What is a word for a non-urgent, not-so-important task? Domino tiling on 8x8 checkerboard with four squares removed How does the operators act on a ket/bra? How to install and play with Mermaid (Markdown Tool) in MACOSX.
Changing the look of the Markdown preview with CSS
Extensions can contribute CSS to change the look or layout of the Markdown preview. Stylesheets are registered using the markdown.previewStylesContribution Point in the extension's package.json:
'markdown.previewStyles' is a list of files relative to the extension's root folder.
Contributed styles are added after the built-in Markdown preview styles but before a user's 'markdown.styles'.
The Markdown Preview GitHub Styling extension is a good example that demonstrates using a stylesheet to make the Markdown preview look like GitHub's rendered Markdown. You can review the extension's source code on GitHub.
Adding support for new syntax with markdown-it plugins
The VS Code Markdown preview supports the CommonMark specification. Extensions can add support for additional Markdown syntax by contributing a markdown-it plugin.
To contribute a markdown-it plugin, first add a 'markdown.markdownItPlugins' contribution in your extension's package.json:
Then, in the extension's main activation function, return an object with a function named extendMarkdownIt. This function takes the current markdown-it instance and must return a new markdown-it instance:
To contribute multiple markdown-it plugins, return multiple use statements chained together:
Extensions that contribute markdown-it plugins are activated lazily, when a Markdown preview is shown for the first time.
The markdown-emoji extension demonstrates using a markdown-it plugin to add emoji support to the markdown preview. You can review the Emoji extension's source code on GitHub.
You may also want to review:
- Guidelines for markdown-it plugin developers
Adding advanced functionality with scripts
For advanced functionality, extensions may contribute scripts that are executed inside of the Markdown preview.
Contributed scripts are loaded asynchronously and reloaded on every content change.
The Markdown Preview Mermaid Support extension demonstrates using scripts to add mermaid diagrams and flowchart support to the markdown preview. You can review the Mermaid extension's source code on GitHub.
I created a crude comparison of the syntax of the various common Markdown extensions to have a better view on what are the most common extensions and what is the most widely accepted syntax for them. The list of Markdown flavors that I looked at was based on the list found on CommonMark's GitHub Wiki.
Github Markdown Mermaid Mod
| Flavor | Superscript | Subscript | Deletion* Strikethrough | Insertion* | Highlight* | Footnote | Task list | Table | Abbr | Deflist | Smart typo | TOC | Math | Math Block | Mermaid |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| GFM | ~~...~~ | - [] ... | + | ||||||||||||
| ExtraMark | ^...^ | ~...~ | {--...--} | {++...++} | {...} | [^...]** | - [] ...** | + | *[...]: ...** | : | |||||
| MultiMarkdown | ^...^^... | ~...~ | {--...--} | {++...++} | {...} | [^...] | + | *[...]: ... | : | + | {{TOC}} | (...) | [...] | ||
| Markdown Extra | [^1] | + | *[...]: ... | : | |||||||||||
| Pandoc | ^...^ | ~...~ | ~~...~~ | [^...] | + | *[...]: ... | : | $...$ | |||||||
| Kramdown | [^1] | + | *[...]: ... | : | |||||||||||
| Markua | ^...^ | ~...~ | ~~...~~{--...--} | {++...++} | {...} | [^...] | + | : | `...`$ | ||||||
| Maruku | [^1] | + | *[...]: ... | : | $...$ | $$ | |||||||||
| Markdown2 | ^...^ | + | |||||||||||||
| Remarkable | ^...^ | ~...~ | ~~...~~ | ++...++ | ... | + | |||||||||
| Showdown | ~~...~~ | [^1] | - [] ... | + | [toc] | $ ... $~...~(...) | [...]```asciimath | ||||||||
| Ghost | ^...^ | ~...~ | ~~...~~ | ... | |||||||||||
| GitLab | ~~...~~{- ... -} | {+ ... +} | [^1] | - [] ... | + | $...$ | ```math | + | |||||||
| Haroopad | ... | - [] ... | [TOC] | + | |||||||||||
| iA Writer | [^1] | - [] ... | + | {{TOC}} | $...$(...) | $$...$$[...] | |||||||||
| Redcarpet | ^(...) | ~~...~~ | ... | [^1] | + | ||||||||||
| ScholarlyMarkdown | $...$``....`` | ```math | |||||||||||||
| Taiga | + | ||||||||||||||
| Trello | ~~...~~ | ||||||||||||||
| s9eTextFormatter | ^...^^... | ~...~ | ~~...~~ |
[*]: Some dialects use the CriticMarkup syntax for these features[**]: Planned in the future
The aim of ExtraMark is to create a well-defined flavor of Markdown that is a clear superset of CommonMark as it is becoming more and more accepted as the de-facto standard for basic Markdown syntax. This project includes the most common syntax extensions for Markdown to have a flavor that could be used by a wide variety of projects and applications.In order to achieve this I created this comparison. Below is the reasoning for the syntax choices for Extramark.
Syntax extensions
Superscript
The ability to create superscript text seems to be a common feature among the various flavors. With the execption of Redcarpet, all implementations support the ^...^ syntax. Some support the variant where the closing ^ is missing, but to keep the snytax unambiguous the closing ^ is required.
Subscript
Just as superscript, subscript is a popular syntax extension. All of the above flavors that support it has the same syntax.
Strikethrough
The stikethrough syntax extension was popularized by GFM and has two syntaxes across implementations. Some variants use the ~~...~~ syntax while dialects use the syntax from CriticMarkup. Some use both.Using CriticMarkup seems the right choice here as it is a somewhat standarized specification for edits in text. Adding support to the GFM style strikethroughs could increase cross compatibility with many dialects.
Insertion
All implementations use some form of the + symbol to denote insertion. Using the CriticMarkup syntax here seems reasonable as it provides specification to all text edit options.
Highlight
As with strikethrough and insertion CriticMarkup also provides solution to this syntax extension. The ... syntax is also widely used so adding support for this could increase compatibilty.
Footnotes
There seems to be a concensus on how to denote footnotes in Markdown. The only difference is that while some dialects only allow numbers as the footnote indicator, others allow any text. The latter is the more universal solution.
This syntax extension is not yet part of ExtraMark!
Does Github Support Mermaid
Task lists
Any implementation that uses task lists uses the snytax of GFM.
This syntax extension is not yet part of ExtraMark!
Tables
Tables are one of the most common feature among Markdown dialects and most use the GFM style tables (some with additions). Using the GFM style seems to be the right path.
Abbreviation
Abbreviations are also a popular feature in Markdown dialects. There is a universal concensus on the syntax.
This syntax extension is not yet part of ExtraMark!
Definition lists
Another common syntax extension is the definition list. The syntax is the same for all dialects.
Smart typo
Some Markdown dialects support transforming common symbols into single characters (e.g. (c) or (tm)). While not a feature that many dialects support it is a pain-free quality of life improvement for writing Markdown documents.
Table of contents
Generating a table of contents with a single 'Markdown tag' can help you save a lot of time, but the single-tag TOC doesn't show the content that actually gets generated.For that I believe a single-tag TOC is an antipattern in Markdown. There are wonderful tools for text editors that can generate a table of contents for any Markdown document with a press of a button.Generating the TOC as a simple nested Markdown list helps maintaining readability and does not violate the original Markdown philosophy: 'A Markdown formatted document should be publishable as-is, as plain text...'.
Math
Math for Markdown is a hard question. There are many implementations and most of them use their own syntax. The two most common syntax elements are using the $ and $$ as delimiters for inline and block math and using LaTeX's (...) and [...] delimiters.As it is already commonplace to use LaTeX for the actual math markup it seems logical to use LaTeX's delimiters but they are very long and hard to read. And the original Markdown philosophy says: 'Readability, however, is emphasized above all else.'. That is an argument for using the $ sign delimiter.There are some hard arguments for and against both methods on the CommonMark forum.
This syntax extension is not yet part of ExtraMark!
Mermaid
Some Markdown dialects allow the creation of diagrams using Mermaid syntax. This seems to contradict the original idea of Markdown documents as these generate some images that should be separate content. For the time being I don't see any good reasons to include Mermaid.
This syntax extension is not part of ExtraMark!
Conclusion
Github Markdown Diagram
Based on these results I created the ExtraMark flavor of Markdown. It ended up being very similar to MultiMarkdown but MultiMarkdown is not based on CommonMark and doesn't have a universal JavaScript implementation.
Github Markdown Mermaids
To use ExtraMark check out its repo on Github.