microsoft / microsoft/monaco-editor

[Bug] `@example` tag immediately followed by code block breaks markdown rendering on the jsDoc preview window

Open
#5,167 1 comment 1 reaction 0 assignees View on GitHub

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?
Monaco Editor Playground Link

https://microsoft.github.io/monaco-editor/playground.html?source=v0.55.1#XQAAAAIJAgAAAAAAAABBqQkHQ5NjdMjwa-jY7SIQ9S7DNlzs5W-mwj0fe1ZCDRFc9ws9XQE0SJE1jc2VKxhaLFIw9vEWSxW3yscw0aLAKAEiAKctgAboa7BDMYJN4ga4GkhMSggRsXm6jL8b9St-UenAzftcdZvGbaj5PqK-az75MxVpUiDROYXmO_z01SNTZe1WoA4CO99-669y6lbzEqLP9Aj8MJfZ7ViUrBSk4eOjHf048GZTz7AHvKKejQI4g1SwmTrA-Hte7mNzoCW6WJjZ_Fio0JJQVZZA8Slj3eujftouSlUOkO9qG31IKleyUDRu4Odug5yg_PZqQ4IuLLrbtSLFU26FB36bBlhs6oWx9Z3A8obsUYcb9V-KhFP_VkLi6ll8lROhiJrwALGQDpV9m-j3QR65JS8TnfxYokrhHILj7uuVgWP1mGeFUvdB41U4TfzIELFpLtRL7vrD_0c3awuHQ3aM9iyBrn7lAj8rV3L12fycjUM

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
  1. Paste the code above into the Monaco playground
  2. Hover over the word first on the last line (const result = first([10, 20, 30]);)
  3. Observe the hover tooltip
  4. Notice that the @example tag 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.

Image
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.

Image
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.