feat: add code callouts (#649)

- [x] I have read the [contributing guidelines](https://github.com/iamgio/quarkdown/blob/main/CONTRIBUTING.md).
- [x] I have tested the changes locally.
- [ ] An issue for this change exists, and it was discussed with maintainers. This is required for new features and non-trivial changes. If present, append `Closes #ISSUE_NUMBER` at the end of this PR description.
- [x] (Optional) I have added necessary documentation to [`docs`](https://github.com/iamgio/quarkdown/tree/main/docs) and [`CHANGELOG.md`](https://github.com/iamgio/quarkdown/blob/main/CHANGELOG.md)

<img width="728" height="438" alt="image" src="https://github.com/user-attachments/assets/7d7720d5-7033-45cc-b0b3-b0e07875c1e1" />


<!-- This is an auto-generated comment: release notes by coderabbit.ai -->
## Summary by CodeRabbit

## New Features

- Added code block callouts with numbered markers linked to explanatory descriptions.
- Callouts support line numbers, focused lines, captions, and code loaded from files.
- Added validation and safe escaping for callout content.
- Added open-ended focused-line ranges for highlighting from a line to the beginning or end.

## Documentation

- Updated code block documentation, changelog, and examples to explain callouts and focus ranges.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: iamgio

.run/CLI_ Mock.run.xml

@@ -2,7 +2,7 @@
   <configuration default="false" name="CLI: Mock" type="JetRunConfigurationType">
     <option name="MAIN_CLASS_NAME" value="com.quarkdown.cli.QuarkdownCliKt" />
     <module name="quarkdown.quarkdown-cli.main" />
-    <option name="PROGRAM_PARAMETERS" value="c main.qd --libs ../quarkdown-libs/src/main/resources" />
+    <option name="PROGRAM_PARAMETERS" value="c main.qd" />
     <shortenClasspath name="NONE" />
     <option name="WORKING_DIRECTORY" value="$PROJECT_DIR$/mock" />
     <method v="2">

.run/CLI_Mock.run.xml

@@ -2,6 +2,23 @@
 
 ## [Unreleased]
 
+### Added
+
+#### [Code block callouts](https://quarkdown.com/wiki/code#callouts)
+
+The new `callouts` argument of the `.code` function attaches numbered markers to specific lines of a code block, each paired with a description displayed right below the block.
+
+```markdown
+.code callouts:{
+    - 3: Defines the horizontal coordinate.
+    - 5: Takes the two coordinates.
+    - 6: Assigns the horizontal coordinate.
+}
+    .read {assets/point.ts}
+```
+
+<img width="660" alt="Callout" src="https://github.com/user-attachments/assets/b2f183ab-0e11-4213-bdd4-7913dd8622c1" />
+
 ### Changed
 
 #### Reflectionless function calls

CHANGELOG.md

@@ -38,12 +38,16 @@ The `.code` function specifies the language through the optional `lang` argument
     .code lang:{typescript}
         .read {assets/point.ts}
 
-### Line numbers
+### Callouts
 
-Standard code blocks always show line numbers by default. The `.code` function lets you toggle line numbers using the optional `linenumbers` [`Boolean`](boolean.qd) argument, which defaults to `yes` (equivalent to `true`).
+The `.code` function can attach numbered markers to specific lines through the optional `callouts` argument, a [`Dictionary`](dictionary.qd) that pairs line numbers with a description.
 
 .examplemirror
-    .code linenumbers:{no}
+    .code callouts:{
+        - 3: Defines the horizontal coordinate.
+        - 5: Takes the two coordinates.
+        - 6: Assigns the horizontal coordinate.
+    }
         .read {assets/point.ts}
 
 ### Focused lines
@@ -54,6 +58,16 @@ The `.code` function allows you to focus on a [`Range`](range.qd) of lines, star
     .code focus:{5..8}
         .read {assets/point.ts}
 
+### Line numbers
+
+Standard code blocks always show line numbers by default. The `.code` function lets you toggle line numbers using the optional `linenumbers` [`Boolean`](boolean.qd) argument, which defaults to `yes` (equivalent to `true`).
+
+.examplemirror
+    .code linenumbers:{no}
+        .read {assets/point.ts}
+
+Note that line numbers are required for callouts and focused lines to work.
+
 ### Extending
 
 `.code` is a [primitive](primitives.qd), so [extending it](element-styling.qd) affects every code block in the document at once, including fenced and indented blocks.

docs/code.qd

@@ -12,11 +12,21 @@
 
 <<<
 
+#### With callouts
+
+.code lang:{java} callouts:{
+	- 4: The constructor.
+	- 8: Getter for the wrapped value.
+}
+	.read {code/Wrapper.java}
+
 #### Focused
 
 .code lang:{java} focus:{4..6}
 	.read {code/Wrapper.java}
 
+<<<
+
 #### Without line numbers
 
 .code lang:{java} linenumbers:{no}

mock/code.qd

@@ -9,6 +9,7 @@ import com.quarkdown.core.ast.quarkdown.CaptionableNode
 import com.quarkdown.core.ast.quarkdown.reference.CrossReferenceableNode
 import com.quarkdown.core.function.dsl.functionCallArguments
 import com.quarkdown.core.function.value.data.Range
+import com.quarkdown.core.function.value.wrappedAsValue
 import com.quarkdown.core.visitor.node.NodeVisitor
 
 /**
@@ -17,7 +18,8 @@ import com.quarkdown.core.visitor.node.NodeVisitor
  * @param language optional syntax language
  * @param showLineNumbers whether to show line numbers
  * @param highlight whether to apply syntax highlighting
- * @param focusedLines range of lines to focus on. No lines are focused if `null`
+ * @param focusedLines range of lines to focus on (1-based). No lines are focused if `null`
+ * @param callouts callout contents associated with line numbers (1-based)
  * @param caption optional caption
  * @param referenceId optional ID for cross-referencing via a [com.quarkdown.core.ast.quarkdown.reference.CrossReference]
  */
@@ -27,6 +29,7 @@ class Code(
     val showLineNumbers: Boolean = true,
     val highlight: Boolean = true,
     val focusedLines: Range? = null,
+    val callouts: Map<Int, String> = emptyMap(),
     override val caption: InlineContent? = null,
     override val referenceId: String? = null,
 ) : LocationTrackableNode,
@@ -46,6 +49,14 @@ class Code(
             arg("caption", inline(caption))
             arg("linenumbers", boolean(showLineNumbers))
             arg("focus", obj(focusedLines))
+            arg(
+                "callouts",
+                dictionary(
+                    callouts
+                        .map { it.key.toString() to it.value.wrappedAsValue() }
+                        .toMap(),
+                ),
+            )
             arg("ref", string(referenceId))
             arg("code", evaluable(content))
         }

quarkdown-core/src/main/kotlin/com/quarkdown/core/ast/base/block/Code.kt

@@ -8,9 +8,11 @@ import com.quarkdown.core.ast.attributes.primitive.PrimitiveFunctionBackedNode
 import com.quarkdown.core.function.call.FunctionCallArgument
 import com.quarkdown.core.function.expression.Expression
 import com.quarkdown.core.function.value.BooleanValue
+import com.quarkdown.core.function.value.DictionaryValue
 import com.quarkdown.core.function.value.NoneValue
 import com.quarkdown.core.function.value.NumberValue
 import com.quarkdown.core.function.value.ObjectValue
+import com.quarkdown.core.function.value.OutputValue
 import com.quarkdown.core.function.value.StringValue
 import com.quarkdown.core.function.value.data.EvaluableString
 import com.quarkdown.core.function.value.wrappedAsValue
@@ -76,6 +78,11 @@ class FunctionCallArgumentsBuilder internal constructor() {
      */
     fun boolean(value: Boolean?): Expression = value?.let(::BooleanValue) ?: NoneValue
 
+    /**
+     * @return [value] wrapped as a dictionary expression, or [NoneValue] if `null`
+     */
+    fun <V : OutputValue<*>> dictionary(value: Map<String, V>?): Expression = value?.let { DictionaryValue(it.toMutableMap()) } ?: NoneValue
+
     /**
      * @return [value] wrapped as an evaluable string, expanded (including nested function calls)
      *         when the resulting argument is evaluated, or [NoneValue] if `null`

quarkdown-core/src/main/kotlin/com/quarkdown/core/function/dsl/FunctionCallArgumentsBuilder.kt

@@ -156,6 +156,14 @@ open class BaseHtmlNodeRenderer(
                     "focus-lines".takeIf { node.focusedLines != null },
                 )
 
+                // Lines marked with a callout, e.g. `data-callouts="1,3,5"`.
+                optionalAttribute(
+                    "data-callouts",
+                    node.callouts.keys
+                        .takeIf { it.isNotEmpty() }
+                        ?.joinToString(","),
+                )
+
                 // Focus range.
                 optionalAttribute("data-focus-start", node.focusedLines?.start)
                 optionalAttribute("data-focus-end", node.focusedLines?.end)

quarkdown-html/src/main/kotlin/com/quarkdown/rendering/html/node/BaseHtmlNodeRenderer.kt

@@ -152,7 +152,11 @@ class QuarkdownHtmlNodeRenderer(
 
             // The reference ID or label is set as the ID of the element, allowing cross-references to link to it.
             val label = node.getLocationLabel(context)
-            val id = (node as? CrossReferenceableNode)?.linkableReferenceId?.let(::sanitizeId) ?: label?.let { "$idPrefix-$it" }
+            val id =
+                (node as? CrossReferenceableNode)
+                    ?.linkableReferenceId
+                    ?.let(::sanitizeId)
+                    ?: label?.let { "$idPrefix-$it" }
             id?.let { optionalAttribute("id", it) }
 
             if (node.caption == null && label == null) {
@@ -688,16 +692,51 @@ class QuarkdownHtmlNodeRenderer(
                 )
             }.build()
 
+    /**
+     * Whether a rendered [Code] block must be wrapped in a `<figure>` tag hosting its caption:
+     * that is, when the block is numbered, captioned, or referenceable via a cross-reference.
+     */
+    private val Code.requiresFigure: Boolean
+        get() = caption != null || getLocationLabel(context) != null || linkableReferenceId != null
+
+    /**
+     * Builds the list of callout descriptions displayed below a code block,
+     * with each item numbered to match the marker attached to its corresponding line of code.
+     * @param callouts callout contents, in marker order
+     * @return the `ul.code-callouts` tag
+     */
+    private fun calloutList(callouts: Collection<String>) =
+        buildTag("ul") {
+            className("code-callouts")
+            callouts.forEachIndexed { index, content ->
+                tag("li") {
+                    className("code-callout")
+                    tag("span") {
+                        className("code-callout-marker")
+                        +(index + 1).toString()
+                    }
+                    +escapeCriticalContent(content)
+                }
+            }
+        }
+
     override fun visit(node: Code): String {
         val block = super.visit(node)
+        val code =
+            if (node.requiresFigure) {
+                buildTag("figure") {
+                    +block
+                    numberedCaption(node, positionProvider = { codeBlocks })
+                }
+            } else {
+                block
+            }
 
-        // If the code is numbered, has a caption, or has a reference ID, it is wrapped in a figure.
-        if (node.caption == null && node.getLocationLabel(context) == null && node.linkableReferenceId == null) {
-            return block
-        }
-        return buildTag("figure") {
-            +block
-            numberedCaption(node, positionProvider = { codeBlocks })
+        if (node.callouts.isEmpty()) return code
+
+        return buildMultiTag {
+            +code
+            +calloutList(node.callouts.values)
         }
     }
 

quarkdown-html/src/main/kotlin/com/quarkdown/rendering/html/node/QuarkdownHtmlNodeRenderer.kt

@@ -70,6 +70,36 @@
     color: white;
   }
 
+  // Code block callouts
+
+  .code-callout-marker {
+    @include font.global-font-family;
+
+    background-color: var(--qd-background-color);
+    font-variant-numeric: tabular-nums;
+    color: var(--qd-main-color);
+    border: 1px solid var(--qd-main-color);
+    border-radius: 100%;
+    padding: 0 var(--qd-digit-circle-padding);
+  }
+
+  pre .code-callout-marker {
+    margin-left: 0.5em;
+  }
+
+  .code-callouts {
+    list-style: none;
+    padding-left: 0;
+
+    .code-callout-marker {
+      margin-right: 0.5em;
+    }
+  }
+
+  :is(pre, figure):has(code[data-callouts]) {
+    margin-bottom: 0;
+  }
+
   // Code block copy button
 
   .hljs-copy-wrapper {