Markdown All in One Documentation

Compatibility

Known issues

Responsiveness and long-running markdown-it plugin

Symptom:

The "Table of Contents" feature shows significant lag.

The whole editor stops responding.

Known cases:

Workaround:

Disable VS Code extensions you don't need until the editor works again.

Occasionally, removing some key bindings can mitigate the problem. See the "Non-keyboard IME" section.

Explanation:

Some markdown-it plugins use algorithms with very high time complexityopen in new window. If multiple VS Code extensions depend on such things, the VS Code extension host may take tens of thousands of milliseconds, because it is single-threaded. Our product loads every markdown-it plugin contributed to VS Code's built-in Markdown previewopen in new window, which may double the time.

Some VS Code extensions don't interact with Markdown documents, but themselves can already slow the extension host, which may worsen the situation.

Reporting a performance issue

Extensions have poor performance due to being single-threaded with other extensions (microsoft/vscode#75627)open in new window

Rendering for math in the Markdown preview

Symptom:

The math and possible other elements in VS Code's built-in Markdown preview do not work as expected.

Known cases:

Workaround:

You can keep only one VS Code extension for such need, and have to disable the others.

Our contribution is controlled by the markdown.extension.math.enabled setting.

vscode.markdown-math's contributionopen in new window is controlled by the markdown.math.enabled setting.

Please consult respective documentation.

Explanation:

When multiple markdown-it plugins with the same goal are loaded at the same time, the result is mostly unpredictable. There can be collision or even worse problems.

Syntax highlighting for math in editor

Symptom:

Syntax highlighting in a Markdown editor is broken, when the document contains pandoc-style math areas.

Known cases:

Workaround:

You can keep only one VS Code extension for such need, and have to disable the others.

The only way to remove TextMate grammar contribution (contributes.grammars)open in new window is disabling the corresponding extension.

Explanation:

The merge result is unpredictable.

Key binding

Symptom:

Some keyboard shortcuts that you're accustomed to are overridden.

Known cases:

Workaround:

Please follow VS Code's detecting and troubleshooting guideopen in new window.

Customize the key bindings to the way it works best for you.

Explanation:

Key binding

Non-keyboard IME

Symptom:

You cannot type characters or snippets that you defined in these IMEs as expected. Random text may be finally inserted.

Vietnamese users may also experience this problem.

People who use keyboard macros may also experience this problem.

People who type very fast may also experience this problem.

Known cases:

Workaround:

Delete key bindingsopen in new window for the markdown.extension.onBackspaceKey command. This effectively removes some of our list editing features.

Explanation:

This issue cannot be resolved in foreseeable future due to how input is handled.

Non-keyboard IME (input method editor) is a kind of programs which can simulate keystrokes as if they were from a physical keyboard. There is no universal term for it. Such IMEs are usually handwriting recognition or voice recognition (speech to text) software. They can dispatch virtual key events at a blazing rate.

When you are editing a Markdown document, we analyze it on each change. Each analysis usually takes tens to hundreds of milliseconds.

To implement list editing features under the current VS Code, we have to hook a lot of keys, such as Backspace, Tab, and Enter. However, we cannot catch up with those IMEs. That's why your input appears lost.

Auto preview

Symptom:

"Auto preview" focuses the wrong editor, or breaks the editor layout.

Known cases:

Workaround:

Do not use this feature. It's disabled by default now.

If you're still using it, disable it at the markdown.extension.preview.autoShowPreviewToSide setting.

Explanation:

The feature is almost discarded. We nowadays can hardly hack VS Code's built-in Markdown previewopen in new window.

Incompatibility

Markdown All in One is not guaranteed to work with Markdown flavors which diverge from CommonMark greatly, or things which customize markdown-it deeply.

The following cases have been identified.

Dependency on vscode.markdown-language-features

This product leverages VS Code's built-in vscode.markdown-language-featuresopen in new window extension.

Commands:

Configuration:

  • markdown.preview.breaks
  • markdown.preview.fontFamily
  • markdown.preview.fontSize
  • markdown.preview.lineHeight
  • markdown.preview.linkify
  • markdown.styles

Contexts:

Markdown preview

This product contributes to VS Code's built-in Markdown previewopen in new window.

It should work harmoniously with other extensions that follow VS Code's guideopen in new window in most cases.

Exporting to HTML

This product uses markdown-itopen in new window to render HTML, and tries to load Markdown extensions in the same way as VS Code.

It should produce nearly the same output as VS Code.