Visual Studio Code – Enabling Markdown for the documentation property of completionItem?

I’m writing my first language extension for VS Code and I find the documentation to be rather difficult to follow. This is of course not helped by me being inexperienced with writing extensions for VS Code, so here I am.

As the subject says, I want to enable Markdown for the documentation property of my completionItem but after literally hours of searching and reading I still don’t know how to do this.

The VS Code Language API tells me to use MarkdownString but VS Code knows nothing about MarkdownString. If I try to reference the deprecated MarkedString the VS Code tooltip documentation for it tells me to use MarkupContent instead.

If I use MarkupContent the tooltip tells me that…

A MarkupContent literal represents a string value which content is interpreted base on its kind flag.

(As an aside, the example on how to construct the string is incorrect which doesn’t inspire confidence).

None the less, it’s easy enough to figure out the problem with the example and I can implement it in my code:

const markdown: MarkupContent = {
  kind: MarkupKind.Markdown,
  value: ""
};

The value is blank as I dynamically define it depending on what item we’re "completing."

I have a list of suggestions that I index using the item.data value sent by the onCompletion function:

const suggestions = [
{
      label: "DATEADD",
      kind: CompletionItemKind.Function,
      insertText: "@DATEADD(${1:<date>}, ${2:<days>})",
      insertTextFormat: InsertTextFormat.Snippet,
      documentation:
        "Adds a specified number of days to the given date, returning the result as a *yyyyMMdd* date.",
},
    ...

I use the documentation property as it’s already present to set the value of markdown.value:

markdown.value = suggestions[item.data].documentation;

After this I assign markdown to suggestions[item.data].documentation:

suggestions[item.data].documentation = markdown;

This doesn’t work though and I get the error "Type ‘MarkupContent’ is not assignable to type ‘string’.", despite the documentation saying that "A MarkupContent literal represents a string value…"

By now I’m certain that I’m doing all of this ass backwards and that there should be a simple flag or property that I can set to tell VS Code that I’m using Markdown for the documentation instead of jumping through all these hoops.

Any tips, tricks, pointers, or straws I can grasp for are more than welcome.

Thanks.