fix: improve semantic structure by linking code and annotation

mcanouil · mcanouil · commit c0f14486008b · 2026-03-07T14:37:08.000+01:00
diff --git a/src/format/typst/format-typst.ts b/src/format/typst/format-typst.ts
@@ -207,7 +207,7 @@ function skylightingPostProcessor(brandBgColor?: string) {
 
   // Annotation markers emitted by the Lua filter as Typst comments
   const annotationMarkerRe =
-    /\/\/ quarto-code-annotations: (\([^)]*\))\n(\s*(?:#block\[\s*)*(?:#quarto-code-filename\([^\n]*\)\[\s*)?)#Skylighting\(/g;
+    /\/\/ quarto-code-annotations: ([\w-]*) (\([^)]*\))\n(\s*(?:#block\[\s*)*(?:#quarto-code-filename\([^\n]*\)\[\s*)?)#Skylighting\(/g;
 
   return async (output: string) => {
     let content = Deno.readTextFileSync(output);
@@ -231,10 +231,10 @@ function skylightingPostProcessor(brandBgColor?: string) {
         );
       }
 
-      // Add annotations parameter to function signature
+      // Add cell-id and annotations parameters to function signature
       fn = fn.replace(
         "start: 1, sourcelines)",
-        "start: 1, annotations: (:), sourcelines)",
+        "start: 1, cell-id: \"\", annotations: (:), sourcelines)",
       );
 
       // Move lnum increment outside if-number block (always track position)
@@ -248,7 +248,12 @@ function skylightingPostProcessor(brandBgColor?: string) {
         "blocks = blocks + ln + EndLine()",
         `let annote-num = annotations.at(str(lnum), default: none)
      if annote-num != none {
-       blocks = blocks + box(width: 100%)[#ln #h(1fr) #quarto-circled-number(annote-num, color: quarto-annote-color(bgcolor))] + EndLine()
+       if cell-id != "" {
+         let lbl = cell-id + "-annote-" + str(annote-num)
+         blocks = blocks + box(width: 100%)[#ln #h(1fr) #link(label(lbl))[#quarto-circled-number(annote-num, color: quarto-annote-color(bgcolor))] #label(lbl + "-back")] + EndLine()
+       } else {
+         blocks = blocks + box(width: 100%)[#ln #h(1fr) #quarto-circled-number(annote-num, color: quarto-annote-color(bgcolor))] + EndLine()
+       }
      } else {
        blocks = blocks + ln + EndLine()
      }`,
@@ -264,7 +269,7 @@ function skylightingPostProcessor(brandBgColor?: string) {
     // optional #block[ wrappers and #quarto-code-filename(...)[ wrappers.
     const merged = content.replace(
       annotationMarkerRe,
-      "$2#Skylighting(annotations: $1, ",
+      "$3#Skylighting(cell-id: \"$1\", annotations: $2, ",
     );
     if (merged !== content) {
       content = merged;
diff --git a/src/resources/filters/quarto-pre/code-annotation.lua b/src/resources/filters/quarto-pre/code-annotation.lua
@@ -108,14 +108,14 @@ end
 
 -- Skylighting mode: emit a Typst comment that the TS post-processor
 -- will merge into the Skylighting call site.
-local function typstAnnotationMarker(annotations)
+local function typstAnnotationMarker(annotations, cellId)
   local dict = typstAnnotationsDict(annotations)
-  return pandoc.RawBlock("typst", "// quarto-code-annotations: " .. dict)
+  return pandoc.RawBlock("typst", "// quarto-code-annotations: " .. (cellId or "") .. " " .. dict)
 end
 
 -- Native/none mode: wrap a CodeBlock in #quarto-code-annotation(annotations)[...].
 -- raw.line numbers always start at 1 regardless of startFrom, so adjust keys.
-local function wrapTypstAnnotatedCode(codeBlock, annotations)
+local function wrapTypstAnnotatedCode(codeBlock, annotations, cellId)
   local startFrom = tonumber(codeBlock.attr.attributes['startFrom']) or 1
   local adjustedAnnotations = {}
   for annoteId, lineNumbers in pairs(annotations) do
@@ -126,14 +126,18 @@ local function wrapTypstAnnotatedCode(codeBlock, annotations)
     adjustedAnnotations[annoteId] = adjusted
   end
   local dict = typstAnnotationsDict(adjustedAnnotations)
+  local cellIdParam = ""
+  if cellId and cellId ~= "" then
+    cellIdParam = ", cell-id: \"" .. cellId .. "\""
+  end
   local lang = codeBlock.attr.classes[1] or ""
   local code = codeBlock.text
   local maxBackticks = 2
   for seq in code:gmatch("`+") do
     maxBackticks = math.max(maxBackticks, #seq)
   end
   local fence = string.rep("`", maxBackticks + 1)
-  local raw = "#quarto-code-annotation(" .. dict .. ")[" .. fence .. lang .. "\n" .. code .. "\n" .. fence .. "]"
+  local raw = "#quarto-code-annotation(" .. dict .. cellIdParam .. ")[" .. fence .. lang .. "\n" .. code .. "\n" .. fence .. "]"
   return pandoc.RawBlock("typst", raw)
 end
 
@@ -497,9 +501,9 @@ function code_annotations()
                       and pendingAnnotations and next(pendingAnnotations) ~= nil then
                     if param(constants.kSyntaxHighlighting, true) then
                       block.content[1].content[1] = codeCell
-                      block.content[1].content:insert(1, typstAnnotationMarker(pendingAnnotations))
+                      block.content[1].content:insert(1, typstAnnotationMarker(pendingAnnotations, pendingCellId))
                     else
-                      block.content[1].content[1] = wrapTypstAnnotatedCode(codeCell, pendingAnnotations)
+                      block.content[1].content[1] = wrapTypstAnnotatedCode(codeCell, pendingAnnotations, pendingCellId)
                     end
                   else
                     block.content[1].content[1] = codeCell
@@ -535,10 +539,10 @@ function code_annotations()
                     and codeAnnotations ~= constants.kCodeAnnotationStyleNone
                     and pendingAnnotations and next(pendingAnnotations) ~= nil then
                   if param(constants.kSyntaxHighlighting, true) then
-                    outputBlock(typstAnnotationMarker(pendingAnnotations))
+                    outputBlock(typstAnnotationMarker(pendingAnnotations, pendingCellId))
                     outputBlock(codeCell)
                   else
-                    outputBlock(wrapTypstAnnotatedCode(codeCell, pendingAnnotations))
+                    outputBlock(wrapTypstAnnotatedCode(codeCell, pendingAnnotations, pendingCellId))
                   end
                 else
                   outputBlock(codeCell)
@@ -560,7 +564,7 @@ function code_annotations()
                 if pendingAnnotations[annoteId] then
                   local content = pandoc.write(pandoc.Pandoc({v[1]}), "typst")
                   annotationBlocks:insert(pandoc.RawBlock("typst",
-                    "#quarto-annotation-item(" .. tostring(annotationNumber) .. ", [" .. content .. "])"))
+                    "#quarto-annotation-item(\"" .. (pendingCellId or "") .. "\", " .. tostring(annotationNumber) .. ", [" .. content .. "])"))
                 end
               end
 
@@ -574,7 +578,7 @@ function code_annotations()
                       if useSkylighting then
                         return nil
                       else
-                        return wrapTypstAnnotatedCode(el, pendingAnnotations)
+                        return wrapTypstAnnotatedCode(el, pendingAnnotations, pendingCellId)
                       end
                     end
                   end
@@ -584,12 +588,12 @@ function code_annotations()
                 if is_custom_node(resolvedCell) then
                   local custom = _quarto.ast.resolve_custom_data(resolvedCell) or pandoc.Div({})
                   if useSkylighting then
-                    custom.content:insert(1, typstAnnotationMarker(pendingAnnotations))
+                    custom.content:insert(1, typstAnnotationMarker(pendingAnnotations, pendingCellId))
                   end
                   custom.content:insert(dlDiv)
                 else
                   if useSkylighting then
-                    resolvedCell.content:insert(1, typstAnnotationMarker(pendingAnnotations))
+                    resolvedCell.content:insert(1, typstAnnotationMarker(pendingAnnotations, pendingCellId))
                   end
                   resolvedCell.content:insert(dlDiv)
                 end
diff --git a/src/resources/formats/typst/pandoc/quarto/definitions.typ b/src/resources/formats/typst/pandoc/quarto/definitions.typ
@@ -59,25 +59,38 @@
   ]
 }
 
-#let quarto-code-annotation(annotations, color: luma(60), body) = {
+#let quarto-code-annotation(annotations, cell-id: "", color: luma(60), body) = {
   show raw.where(block: true): it => it
   show raw.line: it => {
     let annote-num = annotations.at(str(it.number), default: none)
     if annote-num != none {
-      box(width: 100%)[#it #h(1fr) #quarto-circled-number(annote-num, color: color)]
+      if cell-id != "" {
+        let lbl = cell-id + "-annote-" + str(annote-num)
+        box(width: 100%)[#it #h(1fr) #link(label(lbl))[#quarto-circled-number(annote-num, color: color)] #label(lbl + "-back")]
+      } else {
+        box(width: 100%)[#it #h(1fr) #quarto-circled-number(annote-num, color: color)]
+      }
     } else {
       it
     }
   }
   body
 }
 
-#let quarto-annotation-item(n, content) = {
-  block(above: 0.4em, below: 0.4em)[
-    #quarto-circled-number(n)
-    #h(0.4em)
-    #content
-  ]
+#let quarto-annotation-item(cell-id, n, content) = {
+  if cell-id != "" {
+    [#block(above: 0.4em, below: 0.4em)[
+      #link(label(cell-id + "-annote-" + str(n) + "-back"))[#quarto-circled-number(n)]
+      #h(0.4em)
+      #content
+    ] #label(cell-id + "-annote-" + str(n))]
+  } else {
+    block(above: 0.4em, below: 0.4em)[
+      #quarto-circled-number(n)
+      #h(0.4em)
+      #content
+    ]
+  }
 }
 
 // Style native raw code blocks with default inset, radius, and stroke
