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.
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.
Markdown is an easy-to-learn markup language that's used to format plain text documents. Even if you have no previous experience with it, Markdown is so simple that it can be learned in under 10 minutes. For example, if you want to make a word appear italicized, just surround it with asterisks (e.g.test. becomes test). Markdown 教程 Markdown 是一种轻量级标记语言，它允许人们使用易读易写的纯文本格式编写文档。 Markdown 语言在 2004 由约翰格鲁伯（英语：John Gruber）创建。. Markdown can likewise be used to integrate images and hyperlinks in your text. Both are created with a combination of square and round brackets. You can generate a link by placing the anchor text – i.e. The words or phrases visible in the text – in square brackets and inserting the URL in round brackets directly afterwards. HackMD offers a great unified Markdown editor/preview which is familiar and well-suited to our needs. Our meeting records have improved a lot over a short period and as a result we are able to be better accountable to each other as a team. R Markdown supports dozens of static and dynamic output formats including HTML, PDF, MS Word, Beamer, HTML5 slides, Tufte-style handouts, books, dashboards, shiny applications, scientific articles, websites, and more.
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.
Applications
Support
Joplin API - Get Started
Joplin API - References
Development
Google Summer of Code 2021
About
Markdown Definition
Markdown is a simple way to format text that looks great on any device. It doesn't do anything fancy like change the font size, color, or type — just the essentials, using keyboard symbols you already know. Since it is plain text, it is an easy way to author notes and documents and when needed it can be converted to a rich text HTML document.
Joplin desktop and mobile applications can display both the Markdown text and the rendered rich text document.
Joplin follows the CommonMark specification, with additional features added via plugins.
Cheat Sheet🔗
This is a quick summary of the Markdown syntax.
| Markdown | Rendered Output |
|---|---|
| Heading 1 | |
| Heading 2 | Heading 2 |
| Heading 3 | Heading 3 |
| Bold | This is some bold text |
| Italic | This is some italic text |
| Blockquotes | Kent. |
| List |
|
| Ordered list |
|
| Inline code | This is someJavaScript() |
| Code block | Here's some JavaScript code: Language is normally auto-detected, but it can also be specified: |
| Unformatted text | Indent with a tab or 4 spaces for unformatted text. |
| Link | This is detected as a link: https://joplinapp.org And this is a link anchoring text content: Joplin And this is a link, with a title, anchoring text content: Joplin (hint: hover over the link) |
| Images | |
| Horizontal Rule | One rule: Another rule: |
| Tables | See below |
Tables🔗
Tables are created using pipes | and and hyphens -. This is a Markdown table:
Markdown Syntax Cheat Sheet
Which is rendered as:
| First Header | Second Header |
|---|---|
| Content Cell | Content Cell |
| Content Cell | Content Cell |
Markdownlint
Note that there must be at least 3 dashes separating each header cell.
Colons can be used to align columns:
Which is rendered as:
| Tables | Are | Cool |
|---|---|---|
| col 3 is | right-aligned | $1600 |
| col 2 is | centered | $12 |
Joplin Extras🔗
Besides the standard Markdown syntax, Joplin supports several additional features.
Links to other notes🔗
You can create a link to a note by specifying its ID in the URL. For example:
Since getting the ID of a note is not straightforward, each app provides a way to create such link. In the desktop app, right click on a note an select 'Copy Markdown link'. In the mobile app, open a note and, in the top right menu, select 'Copy Markdown link'. You can then paste this link anywhere in another note.
Math notation🔗
Math expressions can be added using the KaTeX notation. To add an inline equation, wrap the expression in $EXPRESSION$, eg. $sqrt{3x-1}+(1+x)^2$. To create an expression block, wrap it as follow:
For example:
Here is an example with the Markdown and rendered result side by side:
Chemical equations🔗
Joplin supports chemical equations via the mhchem plugin for KaTeX. This plugin is automatically enabled if you enable math notation. See the mhchem documentation for the syntax.
Diagrams🔗
You can create diagrams in Joplin using the Mermaid syntax. To add such a graph, wrap the Mermaid script inside a '```mermaid' code block like this:
This is how it would look with the Markdown on the left, and rendered graph on the right:
Note that Mermaid graphs are always rendered on a white background regardless of the current theme. This is because they can contain various colours that may not be compatible with the current theme.
Checkboxes🔗
Checkboxes can be added like so:
Which would turn into:
The checkboxes can then be ticked in the mobile and desktop applications.
HTML support🔗
It is generally recommended to enter the notes as Markdown as it makes the notes easier to edit. However for cases where certain features aren't supported (such as strikethrough or to highlight text), you can also use HTML code directly. For example this would be a valid note:
Plugins🔗
Joplin supports a number of plugins that can be toggled on/off to enable/disable markdown features on top of the standard Markdown features you would expect. These plugins are listed below. Note: not all of the plugins are enabled by default, if the enable field is 'no' below, then open the option screen to enable the plugin. Plugins can be disabled in the same manner.
Note that the functionality added by these plugins is not part of the CommonMark spec so, while they will all work within Joplin, it is not guaranteed that they will work in other Markdown readers. Often this is not an issue but keep it in mind if you require compatibility with other Markdown applications.
Markdownlint Cli
| Plugin | Syntax | Description | Enabled | Screenshot |
|---|---|---|---|---|
| Soft breaks | See breaks markdown-it demo | Joplin uses hard breaks by default, which means that a line break is rendered as <br>. Enable soft breaks for traditional markdown line-break behaviour. | no | View |
| Typographer | See typographer markdown-it demo | Does typographic replacements, (c) -> © and so on | no | View |
| Linkify | See linkify markdown-it demo | Auto-detects URLs and convert them to clickable links | yes | |
| Katex | $$math expr$$ or $math$ | See above | yes | View |
| Fountain | ```fountainYour screenplay... ``` | Adds support for the Fountain markup language, a plain text markup language for screenwriting | no | View |
| Mermaid | ```mermaidmermaid syntax... ``` | See plugin page for full description | yes | View |
| Mark | marked | Transforms into <mark>marked</mark> (highlighted) | yes | View |
| Footnote | Simples inline footnote ^[I'm inline!] | See plugin page for full description | yes | View |
| TOC | Any of ${toc}, [[toc]], [toc], [[_toc_]] | Adds a table of contents to the location of the toc page. Based on headings and sub-headings | yes | View |
| Sub | X~1~ | Transforms into X1 | no | View |
| Sup | X^2^ | Transforms into X2 | no | View |
| Deflist | See pandoc page for syntax | Adds the html <dl> tag accessible through markdown | no | View |
| Abbr | *[HTML]: Hyper Text Markup Language The HTML specification | Allows definition of abbreviations that can be hovered over later for a full expansion | no | View |
| Emoji | :smile: | Transforms into 😄. See this list for more emojis | no | View |
| Insert | ++inserted++ | Transforms into <ins>inserted</ins> () | no | View |
| Multitable | See MultiMarkdown page | Adds more power and customization to markdown tables | no | View |