Support code annotations in fenced markdown code

[samgaudet]

Contribution guidelines

• I've read the contribution guidelines and wholeheartedly agree

I want to suggest an idea and checked that ...

• ... to my best knowledge, my idea wouldn't break something for other users
• ... the documentation does not mention anything about my idea
• ... there are no open or closed issues that are related to my idea

Description

First, let me provide necessary thanks for mkdocs-material as a big fan and avid user.

As far as I can tell, code annotations do not currently function for fenced markdown code. It is possible that I am missing a way to make this work, but tried several possible markdown comment syntaxes to make this work.

In fenced code, I would expect to be able to add an annotation to markdown fenced code using the standard markdown comment syntax (<!--- comment --->), e.g. (remove the \ characters):

\```md
# Title <!--- (1) --->
\```

1. This is an annotation!

Use Cases

As with all fenced code, annotations provide a powerful way to provide additional detail for users without cluttering the page/code block. Having this feature for markdown fenced code would expand the already beneficial feature to even more use cases.

Screenshots / Mockups

Current behavior of the minimal example above:

[squidfunk]

Thanks for reporting. Pygments parses the Markdown code block as follows:

<span class="gh"># Title &lt;!--- (1) ---&gt;</span>

Thus, there's no comment for Material for MkDocs to extract and replace with a code annotation. This is an upstream issue, so you can follow up with this with the maintainers of Pygments, but we can only process what we get. For reference, the logic for extraction can be found here:

mkdocs-material/src/assets/javascripts/components/content/annotation/list/index.ts

Lines 71 to 103 in 59f981e

	function findAnnotationMarkers(container: HTMLElement): Text[] {
	const markers: Text[] = []
	for (const el of getElements(".c, .c1, .cm", container)) {
	const nodes: Text[] = []
	/* Find all text nodes in current element */
	const it = document.createNodeIterator(el, NodeFilter.SHOW_TEXT)
	for (let node = it.nextNode(); node; node = it.nextNode())
	nodes.push(node as Text)
	/* Find all markers in each text node */
	for (let text of nodes) {
	let match: RegExpExecArray | null
	/* Split text at marker and add to list */
	while ((match = /(\(\d+\))(!)?/.exec(text.textContent!))) {
	const [, id, force] = match
	if (typeof force === "undefined") {
	const marker = text.splitText(match.index)
	text = marker.splitText(id.length)
	markers.push(marker)
	/* Replace entire text with marker */
	} else {
	text.textContent = id
	markers.push(text)
	break
	}
	}
	}
	}
	return markers
	}

[samgaudet]

Thanks for the information! Moved this request to a new issue in the pygments project.