Repository navigation
feat(code-blocks): render Material code annotations - #235
Merged
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.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 fixcould 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
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; seeLexer.AllowsLineEndMarkers). So code and output such asprint(1), SQL'sVALUES (1)or a log lineRetrying (1)stay as they are.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 inHighlightedCodeBlockRenderer. The tokens from pairing are reused for rendering.<button popovertarget>with a small raised number. A marker in the middle of a line, such asnet /* (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.jsadds 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.<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.annotate=false|trueafter the language (quoted arguments such as a title are ignored),content.code.annotatein front matter (nested or dotted), andcontent.code.annotateinmdu.yml. The narrowest setting wins. The key follows Material's schema, so later code block settings can go undercontent.code.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 anannotate=.mdu fix: rewrites attribute fences to```yaml title="…". Fence tracking inMarkdownCompatibilitynow honors the fence length and treats a fence with an info string as content, so examples inside code blocks stay untouched.mathblocks are no longer indexed as code.Review notes
heroandicon-searchblocks are now recognized case-insensitively, as a side effect of the shared special-language table. Icon search assets are published in any case too.Testing
dotnet test Mdu.slnpasses (6 skipped, as before). New tests:CodeAnnotationMarkersTest,CodeAnnotationTest,CodeAnnotationsCommandTest.mdu lint Docsis clean.