microsoft / microsoft/monaco-editor
[Bug] `@example` tag immediately followed by code block breaks markdown rendering on the jsDoc preview window
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 46.8k
- Forks
- 4.1k
- Avg merge
- 17h 58m
- Merged PRs (30d)
- 1
Description
Reproducible in vscode.dev or in VS Code Desktop?
- Not reproducible in vscode.dev or VS Code Desktop
Reproducible in the monaco editor playground?
- Not reproducible in the monaco editor playground
Monaco Editor Playground Link
This issue exists in all tested versions (tested back to older versions).
Monaco Editor Playground Code
const value = `/**
* Accesses the first element of an array.
*
* @example
* \`\`\`ts
* A.first([1, 2, 3]); // 1
* A.first([]); // undefined
* \`\`\`
*
* @param array - The input array
* @returns The first element or undefined
*/
export declare function first<T>(array: readonly T[]): T | undefined;
`;
const myEditor = monaco.editor.create(document.getElementById("container"), {
value,
language: "typescript",
automaticLayout: true,
});
Reproduction Steps
- Paste the code above into the Monaco playground
- Hover over the word
firston the last line (const result = first([10, 20, 30]);) - Observe the hover tooltip
- Notice that the
@exampletag and the code block backticks are concatenated on the same line
Actual (Problematic) Behavior
The hover tooltip shows the @example tag concatenated with the opening triple backticks, breaking markdown rendering:
Accesses the first element of an array.
@example — ```ts A.first([1, 2, 3]); // 1 A.first([]); // undefined
*@param*`array` — - The input array
*@returns* — The first element or undefined
The code block is not properly rendered with syntax highlighting, and the formatting is broken. The em dash (—) is inserted by Monaco between the tag and the content, but the newline after @example is ignored, causing the backticks to appear inline.
Expected Behavior
The code block should render properly as a formatted, syntax-highlighted code block, similar to how it appears in VSCode Desktop and vscode.dev.
The @example section should be separated from the code block, and the triple backticks should be recognized as starting a new code block on a new line.
Additional Context
Background
First, thank you for Monaco Editor - it's an incredible tool that powers so many projects! 🙏
I noticed that @example (a standard JSDoc tag) followed immediately by a code block doesn't render properly in Monaco's hover tooltips. Interestingly, VSCode (both desktop and vscode.dev) handles this perfectly, which suggests the solution might already exist in the VSCode codebase.
Current Workaround
Adding descriptive text after @example works great:
/**
* @example Basic usage
* ```ts
* code
* ```
*/
I'm using this workaround in my library documentation for now. While it works, it would be nice to have the flexibility to omit the descriptive text when the code example is self-explanatory, especially since this works fine in VSCode.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Reproduce the issue in the linked Monaco Editor Playground using the provided TypeScript snippet, then inspect the hover tooltip's JSDoc and Markdown rendering path. Compare the behavior with VS Code and vscode.dev, and verify that an @example tag immediately followed by a fenced code block renders as a separate, syntax-highlighted block without requiring descriptive text.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, markdown, typescript
- Domain
- frontend
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 58/100