Motivate extensions to upgrade to MarkdownString

[jrieken]

We will disable command-links in the (deprecated) MarkedString and extension should use the new MarkdownString for command-links.

Background

When using markdown-formatted content, VS Code supports "links" that invoke a command, like so: [Hello](command:myExt.myCommand). This is a powerful feature but has a security concern: With a carefully crafted document and an extension that creates a markdown-string from that content users can be tricked into clicking on what appears to be a link but actually executed a command. Consider the following sample:

• I happen to know that you use an extension that includes potential dangers commands, e.g. running arbitrary commands in a shell
• I make you use my library file that contains a jsdoc-comment invoking such a command via a command-link
• While coding you get a hover saying "click here for more info" which in reality runs a command

To tackle this, we ask extensions to identify their markdown contents as trusted or not. E.g. TypeScript will say it don't trust markdown contents because it doesn't generate it, it just forwards. Other extensions, esp. those that generate command-links on purpose will mark their contents as trusted. To support that we have introduced a new type, MarkdownString. The MarkdownString can be used wherever the MarkedString can be used and when constructing it, you can say if you trust the contents, e.g.

// trusted
const md = new MarkdownString('[My Cool Feature](command:myTrustedContents)')
md.isTrusted = true;

// not trusted
new MarkdownString(forgeinContentsLikeJsDoc)

[jrieken]

Extensions that are known to use command-links and that need updating during the September timeframe:

• solargraph - Deprecation - use MarkdownString for command-links castwide/vscode-solargraph#11
• vscode-translate-hover - not found?
• quokka-vscode - Deprecation - use MarkdownString for command-links wallabyjs/quokka#90
• kite - not found?
• elastic - not found?
• godot-tools - Deprecation - use MarkdownString for command-links godotengine/godot-vscode-plugin#40

[ArtemGovorov]

// trusted
new MarkdownString('[My Cool Feature](command:myTrustedContents)', true)

The MarkdownString constructor only has one parameter. Should it be:

// trusted
const md = new MarkdownString('[My Cool Feature](command:myTrustedContents)');
md.isTrusted = true;

?

[castwide]

TypeScript does not recognize MarkdownString, either as a stand-alone constant or inside the vscode namespace.

import * as vscode from 'vscode';
new MarkdownString // <- unrecognized
new vscode.MarkdownString // <- unrecognized

I'm using vscode module 1.1.5 and engine 1.5.0. I fetched vscode.d.ts from https://raw.githubusercontent.com/Microsoft/vscode/4fc690be310dd02e0ab6529c0b9bf348a8b26a19/src/vs/vscode.d.ts. Is there something I'm missing?

[jrieken]

Good catch @ArtemGovorov - me thinking about new ideas that aren't implemented yet... Yeah, today we only have the property. I'll update the samples...

[jrieken]

@castwide We will ship the 1.16 release today, then you can get the latest API by setting the engine-field in package.json to 1.16. Run npm i after that and our scripts will download the latest version of vscode.d.ts

[metaleap]

MarkedString had a property language that was actually supremely handy and that I used quite a bit. MarkdownString no longer has that. Is that coming back by any chance? It wasn't harmful and it actually proved useful. Kinda 'tabula rasa' to just throw it out and have everyone code-bloat / wheel-reinvent their own workaround via markdown's triple-backtick syntax, when vscode used to readily handle it so smoothly before.

[jrieken]

MarkedString had a property language that was actually supremely handy and that I used quite a bit. MarkdownString no longer has that.

It has it. The {language, value} part of MarkedString is nothing else than a triple back-tic and text. Like you have code blocks inside markdown, just more verbose. The string portion of both (MarkedString and Markdown) support this, like all the other markdown things (bullet list, links, inline code, italic, bold, etc...). The only reason the verbose-part exists is that in beginning we didn't support any markdown but stuff was just a string or a code block. Ever since we started to support more markdown the verbose variant as been obsolete.

[KamasamaK]

I was looking for an example to replace the language-highlighted version, but found that VS Code's own extensions still use {language, value} (Example).

Are you saying this would be replaced with something like new MarkdownString('```' + language + ' ' + value + '```') (or the template string equivalent)?

[jrieken]

Are you saying this would be replaced with something like new MarkdownString('' + language + ' ' + value + '') (or the template string equivalent)?

Almost, newline character after language and the value are missing

[abe33]

Hi all, Kite's maintainer here, I didn't noticed that issue until recently and I just wanted to let you know that our next release will include the change to use MarkdownString instead of MarkedString.

[KamasamaK]

@jrieken Thanks for clarifying. You're right, it is a bit verbose. What do you think about adding a new method to MarkdownString called something like appendLanguageBlock?

[jrieken]

Yeah, we can do that. Actually, internally we have it already and I just didn't know what all to expose in the API...

[KamasamaK]

Sounds great! Actually, after thinking about it a bit more, perhaps it should just be appendCodeBlock which optionally takes a language.

[jrieken]

done

[KamasamaK]

@jrieken Wow, that was fast! A bit nit picky, but since "code block" is generally written as two words, shouldn't the b be upper case?

[jrieken]

Yeah, did that on purpose because it somehow felt better...

[seanmcbreen]

I think this issue can now be closed - LMK if that was the wrong call.

Sean
VS Code