Skip to content

feat(code-blocks): render Material code annotations - #235

Merged
capjan merged 9 commits into
mainfrom
feat/code-annotations
Nov 14, 2026
Merged

capjan merged 9 commits into
mainfrom
feat/code-annotations

Conversation

@capjan

@capjan capjan commented Nov 14, 2026 •

Copy link
Copy Markdown
Owner

What

Code blocks can now carry annotations in the syntax of Material for MkDocs. A marker such as (1) in a comment becomes a numbered button. The button opens the matching entry of the numbered list directly after the code block as a popover.

site:
  name: Acme Docs # (1)!
  1. Shown in the header and in the browser tab.

Why

Code annotations are one of the most used features of Material for MkDocs, which reaches its end of life on May 5, 2027. Until now mdu fix could only drop them, so migrated pages lost their explanations. Pages now render as they are, and the source stays readable on GitHub as a comment plus a numbered list.

How it works

  • Markers (StaticCode.Highlighter/CodeAnnotationMarkers.cs): (n) counts anywhere in a comment token, and (n)! there also removes an otherwise empty comment (#, //, --, <!-- -->). Outside comments only the explicit form (n)! counts, at the end of a line after a space, and only in shell commands and in blocks without comments (text, console output, JSON, unknown languages; see Lexer.AllowsLineEndMarkers). So code and output such as print(1), SQL's VALUES (1) or a log line Retrying (1) stay as they are.
  • Pairing (Markdown.Renderer/CodeAnnotations.cs): a fenced code block followed by an ordered list that starts at 1, optionally after a [!RESULT] block, is annotated when at least one marker matches an entry. The list moves into the code block and stops being an ordinary list; headings in it get no id, as in result blocks. Diagrams, math, hero and icon search blocks are never paired, using one shared table of special languages in HighlightedCodeBlockRenderer. The tokens from pairing are reused for rendering.
  • HTML: each marker is a <button popovertarget> with a small raised number. A marker in the middle of a line, such as net /* (1)! */, floats above the end of its word and takes no width, so the code keeps its spacing; blocks with such markers get a uniform line height of 2. A marker in a comment at the end of a line sits in the line. At rest numbers are secondary grey without a background; they fill with the link color on hover, while open, or while their legend entry is pointed at. Each has a 24px hit area centered on the number. The entries are <li popover> elements that start with their number and fade in and out; CSS anchor positioning places them below the marker. Clicking works without JavaScript. code-copy.js adds hover opening after 100 ms and closing 125 ms after leaving (the pointer can move onto the explanation), pinning by click, opening on keyboard focus, placing the popover at the marker that was used, and highlighting between markers and legend. The copy button copies the code without markers.
  • Legend: a collapsible <details> footer of the code card lists all explanations. It starts closed, highlights the entry of an open marker, opens for print, and is what browsers without popovers show.
  • PDF: markers are small raised numbers that take no width, without the comments that only held them, and the entries follow as a compact legend with number bubbles. Code lines no longer clip descenders. Pairing runs after hidden PDF content is removed. Render, serve and pdf pass the site setting to the PDF.
  • Switches: annotate=false|true after the language (quoted arguments such as a title are ignored), content.code.annotate in front matter (nested or dotted), and content.code.annotate in mdu.yml. The narrowest setting wins. The key follows Material's schema, so later code block settings can go under content.code.
  • Lint: MDU029 (marker without entry, warning), MDU030 (entry without marker, warning; points to annotate=false), MDU031 (invalid setting, error). MDU011 now also reports Material attribute fences such as ``` { .yaml .annotate } and says that code annotations work. Lint parses a page for this only when it has a fence and a numbered list starting at 1, or an annotate=.
  • mdu fix: rewrites attribute fences to ```yaml title="…". Fence tracking in MarkdownCompatibility now honors the fence length and treats a fence with an info string as content, so examples inside code blocks stay untouched.
  • Search: annotated code is indexed without its markers, following the page and site settings, and headings in annotations start no search section. Search uses the renderer's check for code languages, so math blocks are no longer indexed as code.

Review notes

  • hero and icon-search blocks are now recognized case-insensitively, as a side effect of the shared special-language table. Icon search assets are published in any case too.
  • Keyboard focus follows AGENTS.md: the marker gets an inset ring and turns light while focused, since the scrolling code clips overflow.

Testing

  • dotnet test Mdu.sln passes (6 skipped, as before). New tests: CodeAnnotationMarkersTest, CodeAnnotationTest, CodeAnnotationsCommandTest.
  • mdu lint Docs is clean.
  • Checked in a served page: tab to a marker, Enter opens it, Esc closes it and keeps focus; light and dark; 375 px width keeps a 16 px gutter with no horizontal scroll; a repeated marker opens next to the marker that was used.
  • Not checked: a browser without popover support, printing from the browser, and the list role with a screen reader.

Markers such as (1) in a code comment, or at the end of a line after a
space, become buttons that open the matching entry of the numbered list
after the code block as a popover. The syntax is the one of Material
for MkDocs, so migrated pages need no changes.

- Popovers work without JavaScript and open next to the marker that
  was used; the copy button copies the code without markers.
- The PDF shows markers as (1) and the entries below the code.
- content.code.annotate in mdu.yml or the front matter and annotate=
  on a code block switch annotations; the narrowest setting wins.
- Lint warns about markers without entries (MDU029) and entries
  without markers (MDU030), reports invalid settings (MDU031), and
  MDU011 now also reports Material attribute fences.
- mdu fix turns fences such as { .yaml .annotate } into plain
  languages, and fence tracking honors the fence length.
- The search index stores annotated code without markers.
- Markers outside comments count only in shell commands and in blocks
  without comments, so SQL's VALUES (1) or Python's x = (1) stay code
  and a numbered list after them stays a list.
- A fence closes only with nothing after it, so a ```yaml line inside
  a code example no longer ends it for lint and mdu fix.
- Icon search blocks publish their assets in any letter case.
- Headings in annotations get no id, so they stay out of the page
  contents and get no permalink.
- annotate= inside a quoted title is text, not the switch.
- The search index follows the page and site annotation settings.
- Lint parses a page for annotations only when it has a fence and a
  numbered list, or an annotate= setting.
- The annotation list keeps its box, and with it the list role.
A plain " (1)" at the end of a line is often code or output, such as
VALUES (1) in a language without a grammar or a retry counter in a
log. Outside comments only the explicit form (1)! now counts; markers
in comments work as before.

- Search uses the renderer's check for code languages, so math blocks
  are no longer indexed as code, and gets the page's annotation setting
  as a parameter. Render and serve pass the site setting to the
  visitor instead of reading it from the renderer.
- Headings in annotations no longer start search sections, since they
  have no anchor on the page.
- The PDF test reads all text of the document, independent of how the
  writer splits a line into runs.
Markers are now small raised numbers right after the word they
explain, like footnote references, instead of buttons between words.
Lines with a marker keep their height, and the marker takes clicks
and taps on a 24px square. A marker after visible comment characters
such as "# (1)" keeps its space, and one alone on a line keeps its
indentation.

Copying keeps the space after a marker in the middle of a line, so
"sum /* (1)! */ * days" copies as "sum * days".

The documentation shows how to annotate the operands of a calculation
with block comments.
A comment at the end of a line explains the whole line, so it now
stays visible with its marker after it, also with (1)!. Only an
otherwise empty comment between code, such as net /* (1)! */ * rate,
makes way for its marker. Copying still drops comments that held
nothing but markers, including their closing */ or -->.

Markers rest as a soft tint, so they no longer compete with keywords
in the link color, and fill on hover and while their explanation is
open. Only the marker that opened an explanation is filled when a
number appears more than once.
Markers in the middle of a line now float above the end of their word
and take no width, so annotated code keeps its own spacing; blocks with
such markers get a uniform, larger line height so the numbers never
cover the line above. Markers in a comment at the end of a line stay
in the line. At rest the numbers are secondary grey without a
background and fill with the link color on hover, while open, or
while their legend entry is pointed at.

Pointing at a marker opens its explanation after a short delay, like a
footnote preview, and leaving marker and explanation closes it. A click
pins it until a click elsewhere or Esc; keyboard focus opens it; touch
keeps tapping. Each popover starts with its number and fades in and
out without its layout moving.

A collapsible legend below the code lists all explanations. It starts
closed, highlights the entry of an open marker, opens for print, and
replaces the fallback list in browsers without popovers.

In the PDF, markers are small raised numbers without the comments that
only held them, code lines no longer clip descenders, and the legend
lists the entries with number bubbles. The documentation shows the
multi-line Billing example.
- A pinned explanation stays open while the pointer passes other
  markers; a click moves the pin.
- Each annotation entry is rendered once; the legend shows a copy
  without ids, so footnote references and other ids appear once.
- Without the Popover API, a click on a marker opens the legend and
  highlights its entry.
- Print shows the legend entries through ::details-content also
  without JavaScript.
- The tint of legend numbers is a theme token.
- In the PDF, a legend entry at the top of a page keeps its bubble on
  the line of its text.
@capjan
capjan merged commit 8f46f77 into main Nov 14, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant