Add support to (@) lists (#6)

cscheid · cscheid · commit 69676807a699 · 2025-10-14T19:21:55.000-05:00
diff --git a/crates/quarto-markdown-pandoc/src/pandoc/ast_context.rs b/crates/quarto-markdown-pandoc/src/pandoc/ast_context.rs
@@ -3,31 +3,39 @@
  * Copyright (c) 2025 Posit, PBC
  */
 
+use std::cell::Cell;
+
 /// Context passed through the parsing pipeline to provide information
 /// about the current parse operation and manage string ownership.
 /// The filenames vector will eventually be used to deduplicate strings
 /// in the AST by storing indices instead of cloning strings.
 #[derive(Debug, Clone)]
 pub struct ASTContext {
     pub filenames: Vec<String>,
+    /// Counter for example list numbering across the document
+    /// Example lists continue numbering even when interrupted by other content
+    pub example_list_counter: Cell<usize>,
 }
 
 impl ASTContext {
     pub fn new() -> Self {
         ASTContext {
             filenames: Vec::new(),
+            example_list_counter: Cell::new(1),
         }
     }
 
     pub fn with_filename(filename: impl Into<String>) -> Self {
         ASTContext {
             filenames: vec![filename.into()],
+            example_list_counter: Cell::new(1),
         }
     }
 
     pub fn anonymous() -> Self {
         ASTContext {
             filenames: Vec::new(),
+            example_list_counter: Cell::new(1),
         }
     }
 
diff --git a/crates/quarto-markdown-pandoc/src/pandoc/list.rs b/crates/quarto-markdown-pandoc/src/pandoc/list.rs
@@ -6,6 +6,7 @@
 #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
 pub enum ListNumberStyle {
     Default,
+    Example,
     Decimal,
     LowerRoman,
     UpperRoman,
diff --git a/crates/quarto-markdown-pandoc/src/pandoc/treesitter.rs b/crates/quarto-markdown-pandoc/src/pandoc/treesitter.rs
@@ -112,7 +112,10 @@ fn process_list(
             // this is a marker node, we don't need to do anything with it
             continue;
         }
-        if node == "list_marker_parenthesis" || node == "list_marker_dot" {
+        if node == "list_marker_parenthesis"
+            || node == "list_marker_dot"
+            || node == "list_marker_example"
+        {
             // this is an ordered list, so we need to set the flag
             let PandocNativeIntermediate::IntermediateOrderedListMarker(marker_number, _) = child
             else {
@@ -121,10 +124,14 @@ fn process_list(
 
             is_ordered_list = Some((
                 marker_number,
-                ListNumberStyle::Decimal,
+                match node.as_str() {
+                    "list_marker_example" => ListNumberStyle::Example,
+                    _ => ListNumberStyle::Decimal,
+                },
                 match node.as_str() {
                     "list_marker_parenthesis" => ListNumberDelim::OneParen,
                     "list_marker_dot" => ListNumberDelim::Period,
+                    "list_marker_example" => ListNumberDelim::TwoParens,
                     _ => panic!("Unexpected list marker node: {}", node),
                 },
             ));
@@ -244,7 +251,14 @@ fn process_list(
     };
 
     match is_ordered_list {
-        Some(attr) => {
+        Some(mut attr) => {
+            // For example lists, use and update the global counter
+            if attr.1 == ListNumberStyle::Example {
+                let start_num = context.example_list_counter.get();
+                attr.0 = start_num;
+                // Increment counter by the number of items in this list
+                context.example_list_counter.set(start_num + content.len());
+            }
             PandocNativeIntermediate::IntermediateBlock(Block::OrderedList(OrderedList {
                 attr,
                 content,
@@ -267,7 +281,10 @@ fn process_list_item(
     let children = children
         .into_iter()
         .filter_map(|(node, child)| {
-            if node == "list_marker_dot" || node == "list_marker_parenthesis" {
+            if node == "list_marker_dot"
+                || node == "list_marker_parenthesis"
+                || node == "list_marker_example"
+            {
                 // this is an ordered list, so we need to set the flag
                 let PandocNativeIntermediate::IntermediateOrderedListMarker(marker_number, _) =
                     child
@@ -276,10 +293,14 @@ fn process_list_item(
                 };
                 list_attr = Some((
                     marker_number,
-                    ListNumberStyle::Decimal,
+                    match node.as_str() {
+                        "list_marker_example" => ListNumberStyle::Example,
+                        _ => ListNumberStyle::Decimal,
+                    },
                     match node.as_str() {
                         "list_marker_parenthesis" => ListNumberDelim::OneParen,
                         "list_marker_dot" => ListNumberDelim::Period,
+                        "list_marker_example" => ListNumberDelim::TwoParens,
                         _ => panic!("Unexpected list marker node: {}", node),
                     },
                 ));
@@ -568,7 +589,7 @@ fn native_visitor<T: Write>(
         "shortcode_boolean" => process_shortcode_boolean(node, input_bytes, context),
         "shortcode_number" => process_shortcode_number(node, input_bytes, context),
         "code_fence_content" => process_code_fence_content(node, children, input_bytes, context),
-        "list_marker_parenthesis" | "list_marker_dot" => {
+        "list_marker_parenthesis" | "list_marker_dot" | "list_marker_example" => {
             process_list_marker(node, input_bytes, context)
         }
         // These are marker nodes, we don't need to do anything with it
diff --git a/crates/quarto-markdown-pandoc/src/pandoc/treesitter_utils/list_marker.rs b/crates/quarto-markdown-pandoc/src/pandoc/treesitter_utils/list_marker.rs
@@ -20,7 +20,19 @@ pub fn process_list_marker(
         // we trim both ends instead of just trim_end()
         // because the lexer might hand us a marker with tabs at the beginning,
         // as a result of weird mixed-spaces-and-tabs cases like "> \t1."
-        .trim()
+        .trim();
+
+    // Check if this is an example list marker (@)
+    if marker_text == "(@)" {
+        // For example lists, we use 1 as the starting number
+        // The actual numbering will be handled in postprocessing
+        return PandocNativeIntermediate::IntermediateOrderedListMarker(
+            1,
+            node_source_info_with_context(node, context).range,
+        );
+    }
+
+    let marker_text = marker_text
         .trim_end_matches('.')
         .trim_end_matches(')')
         .to_string();
diff --git a/crates/quarto-markdown-pandoc/src/pandoc/treesitter_utils/postprocess.rs b/crates/quarto-markdown-pandoc/src/pandoc/treesitter_utils/postprocess.rs
@@ -259,7 +259,6 @@ fn transform_definition_list_div(div: Div) -> Block {
     })
 }
 
-
 /// Apply post-processing transformations to the Pandoc AST
 pub fn postprocess(doc: Pandoc) -> Result<Pandoc, Vec<String>> {
     let mut errors = Vec::new();
diff --git a/crates/quarto-markdown-pandoc/src/readers/json.rs b/crates/quarto-markdown-pandoc/src/readers/json.rs
@@ -640,7 +640,10 @@ fn read_ast_context(value: &Value) -> Result<ASTContext> {
         })
         .collect::<Result<Vec<_>>>()?;
 
-    Ok(ASTContext { filenames })
+    Ok(ASTContext {
+        filenames,
+        example_list_counter: std::cell::Cell::new(1),
+    })
 }
 
 pub fn read<R: std::io::Read>(reader: &mut R) -> Result<(Pandoc, ASTContext)> {
diff --git a/crates/quarto-markdown-pandoc/src/writers/json.rs b/crates/quarto-markdown-pandoc/src/writers/json.rs
@@ -192,6 +192,7 @@ fn write_list_attributes(attr: &ListAttributes) -> Value {
         crate::pandoc::ListNumberStyle::UpperAlpha => json!({"t": "UpperAlpha"}),
         crate::pandoc::ListNumberStyle::LowerRoman => json!({"t": "LowerRoman"}),
         crate::pandoc::ListNumberStyle::UpperRoman => json!({"t": "UpperRoman"}),
+        crate::pandoc::ListNumberStyle::Example => json!({"t": "Example"}),
         crate::pandoc::ListNumberStyle::Default => json!({"t": "Default"}),
     };
     let number_delimiter = match attr.2 {
diff --git a/crates/quarto-markdown-pandoc/src/writers/native.rs b/crates/quarto-markdown-pandoc/src/writers/native.rs
@@ -358,6 +358,7 @@ fn write_list_number_style<T: std::io::Write>(
         crate::pandoc::ListNumberStyle::UpperAlpha => write!(buf, "UpperAlpha"),
         crate::pandoc::ListNumberStyle::LowerRoman => write!(buf, "LowerRoman"),
         crate::pandoc::ListNumberStyle::UpperRoman => write!(buf, "UpperRoman"),
+        crate::pandoc::ListNumberStyle::Example => write!(buf, "Example"),
         crate::pandoc::ListNumberStyle::Default => write!(buf, "Decimal"), // Is this supposed to be the default?
     }
 }
diff --git a/crates/quarto-markdown-pandoc/src/writers/qmd.rs b/crates/quarto-markdown-pandoc/src/writers/qmd.rs
@@ -5,7 +5,7 @@
 
 use crate::pandoc::attr::is_empty_attr;
 use crate::pandoc::block::MetaBlock;
-use crate::pandoc::list::ListNumberDelim;
+use crate::pandoc::list::{ListNumberDelim, ListNumberStyle};
 use crate::pandoc::meta::MetaValue;
 use crate::pandoc::table::{Alignment, Cell, Table};
 use crate::pandoc::{
@@ -101,12 +101,18 @@ struct OrderedListContext<'a, W: Write + ?Sized> {
     at_line_start: bool,
     is_first_line: bool,
     number: usize,
+    number_style: ListNumberStyle,
     delimiter: ListNumberDelim,
     indent: String,
 }
 
 impl<'a, W: Write + ?Sized> OrderedListContext<'a, W> {
-    fn new(inner: &'a mut W, number: usize, delimiter: ListNumberDelim) -> Self {
+    fn new(
+        inner: &'a mut W,
+        number: usize,
+        number_style: ListNumberStyle,
+        delimiter: ListNumberDelim,
+    ) -> Self {
         // Pandoc uses consistent spacing: for numbers < 10, uses two spaces after delimiter
         // For numbers >= 10, uses one space. Continuation lines always use 4 spaces indent.
         let indent = "    ".to_string(); // Always 4 spaces for continuation lines
@@ -116,6 +122,7 @@ impl<'a, W: Write + ?Sized> OrderedListContext<'a, W> {
             at_line_start: true,
             is_first_line: true,
             number,
+            number_style,
             delimiter,
             indent,
         }
@@ -128,18 +135,23 @@ impl<'a, W: Write + ?Sized> Write for OrderedListContext<'a, W> {
         for &byte in buf {
             if self.at_line_start {
                 if self.is_first_line {
-                    let delim_str = match self.delimiter {
-                        ListNumberDelim::Period => ".",
-                        ListNumberDelim::OneParen => ")",
-                        ListNumberDelim::TwoParens => ")",
-                        _ => ".",
-                    };
-                    // Pandoc style: numbers < 10 get two spaces after delimiter,
-                    // numbers >= 10 get one space
-                    if self.number < 10 {
-                        write!(self.inner, "{}{}  ", self.number, delim_str)?;
+                    // For example lists, always use (@) marker
+                    if matches!(self.number_style, ListNumberStyle::Example) {
+                        write!(self.inner, "(@)  ")?;
                     } else {
-                        write!(self.inner, "{}{} ", self.number, delim_str)?;
+                        let delim_str = match self.delimiter {
+                            ListNumberDelim::Period => ".",
+                            ListNumberDelim::OneParen => ")",
+                            ListNumberDelim::TwoParens => ")",
+                            _ => ".",
+                        };
+                        // Pandoc style: numbers < 10 get two spaces after delimiter,
+                        // numbers >= 10 get one space
+                        if self.number < 10 {
+                            write!(self.inner, "{}{}  ", self.number, delim_str)?;
+                        } else {
+                            write!(self.inner, "{}{} ", self.number, delim_str)?;
+                        }
                     }
                     self.is_first_line = false;
                 } else {
@@ -331,7 +343,7 @@ fn write_orderedlist(
     orderedlist: &OrderedList,
     buf: &mut dyn std::io::Write,
 ) -> std::io::Result<()> {
-    let (start_num, _number_style, delimiter) = &orderedlist.attr;
+    let (start_num, number_style, delimiter) = &orderedlist.attr;
 
     // Determine if this is a tight list
     // A list is tight if the first block of all items is Plain (not Para)
@@ -346,7 +358,8 @@ fn write_orderedlist(
             writeln!(buf)?;
         }
         let current_num = start_num + i;
-        let mut item_writer = OrderedListContext::new(buf, current_num, delimiter.clone());
+        let mut item_writer =
+            OrderedListContext::new(buf, current_num, number_style.clone(), delimiter.clone());
         for (j, block) in item.iter().enumerate() {
             if j > 0 && !is_tight {
                 // Add a blank line between blocks within a list item in loose lists
diff --git a/crates/quarto-markdown-pandoc/tests/pandoc-match-corpus/markdown/060.qmd b/crates/quarto-markdown-pandoc/tests/pandoc-match-corpus/markdown/060.qmd
@@ -0,0 +1,9 @@
+(@) First item
+
+(@) Second item
+
+Some text in between.
+
+(@) Third item
+
+(@) Fourth item
diff --git a/crates/quarto-markdown-pandoc/tests/smoke/020.qmd b/crates/quarto-markdown-pandoc/tests/smoke/020.qmd
@@ -0,0 +1,5 @@
+(@) First item
+
+(@) Second item
+
+(@) Third item
diff --git a/crates/quarto-markdown-pandoc/tests/smoke/021.qmd b/crates/quarto-markdown-pandoc/tests/smoke/021.qmd
@@ -0,0 +1,9 @@
+(@) First item
+
+(@) Second item
+
+Some text in between.
+
+(@) Third item
+
+(@) Fourth item
diff --git a/crates/tree-sitter-qmd/tree-sitter-markdown/grammar.js b/crates/tree-sitter-qmd/tree-sitter-markdown/grammar.js
@@ -277,20 +277,23 @@ module.exports = grammar({
             $._list_minus,
             $._list_star,
             $._list_dot,
-            $._list_parenthesis
+            $._list_parenthesis,
+            $._list_example
         )),
         _list_plus: $ => prec.right(repeat1(alias($._list_item_plus, $.list_item))),
         _list_minus: $ => prec.right(repeat1(alias($._list_item_minus, $.list_item))),
         _list_star: $ => prec.right(repeat1(alias($._list_item_star, $.list_item))),
         _list_dot: $ => prec.right(repeat1(alias($._list_item_dot, $.list_item))),
         _list_parenthesis: $ => prec.right(repeat1(alias($._list_item_parenthesis, $.list_item))),
+        _list_example: $ => prec.right(repeat1(alias($._list_item_example, $.list_item))),
         // Some list items can not interrupt a paragraph and are marked as such by the external
         // scanner.
         list_marker_plus: $ => choice($._list_marker_plus, $._list_marker_plus_dont_interrupt),
         list_marker_minus: $ => choice($._list_marker_minus, $._list_marker_minus_dont_interrupt),
         list_marker_star: $ => choice($._list_marker_star, $._list_marker_star_dont_interrupt),
         list_marker_dot: $ => choice($._list_marker_dot, $._list_marker_dot_dont_interrupt),
         list_marker_parenthesis: $ => choice($._list_marker_parenthesis, $._list_marker_parenthesis_dont_interrupt),
+        list_marker_example: $ => choice($._list_marker_example, $._list_marker_example_dont_interrupt),
         _list_item_plus: $ => seq(
             $.list_marker_plus,
             optional($.block_continuation),
@@ -326,6 +329,13 @@ module.exports = grammar({
             $._block_close,
             optional($.block_continuation)
         ),
+        _list_item_example: $ => seq(
+            $.list_marker_example,
+            optional($.block_continuation),
+            $._list_item_content,
+            $._block_close,
+            optional($.block_continuation)
+        ),
         // List items are closed after two consecutive blank lines
         _list_item_content: $ => choice(
             prec(1, seq(
@@ -540,6 +550,8 @@ module.exports = grammar({
         $._list_marker_star_dont_interrupt,
         $._list_marker_parenthesis_dont_interrupt,
         $._list_marker_dot_dont_interrupt,
+        $._list_marker_example,
+        $._list_marker_example_dont_interrupt,
         $._fenced_code_block_start_backtick,
         $._fenced_code_block_start_tilde,
         $._blank_line_start, // Does not contain the newline characters. Blank lines do not need a `$._block_close`
diff --git a/crates/tree-sitter-qmd/tree-sitter-markdown/src/grammar.json b/crates/tree-sitter-qmd/tree-sitter-markdown/src/grammar.json
diff --git a/crates/tree-sitter-qmd/tree-sitter-markdown/src/node-types.json b/crates/tree-sitter-qmd/tree-sitter-markdown/src/node-types.json
diff --git a/crates/tree-sitter-qmd/tree-sitter-markdown/src/parser.c b/crates/tree-sitter-qmd/tree-sitter-markdown/src/parser.c
diff --git a/crates/tree-sitter-qmd/tree-sitter-markdown/src/scanner.c b/crates/tree-sitter-qmd/tree-sitter-markdown/src/scanner.c
diff --git a/crates/tree-sitter-qmd/tree-sitter-markdown/test/corpus/qmd.txt b/crates/tree-sitter-qmd/tree-sitter-markdown/test/corpus/qmd.txt

Original file line number	Diff line number	Diff line change
`@@ -3,31 +3,39 @@`
`3`	`3`	`* Copyright (c) 2025 Posit, PBC`
`4`	`4`	`*/`
`5`	`5`
	`6`	`+use std::cell::Cell;`
	`7`	`+`
`6`	`8`	`/// Context passed through the parsing pipeline to provide information`
`7`	`9`	`/// about the current parse operation and manage string ownership.`
`8`	`10`	`/// The filenames vector will eventually be used to deduplicate strings`
`9`	`11`	`/// in the AST by storing indices instead of cloning strings.`
`10`	`12`	`#[derive(Debug, Clone)]`
`11`	`13`	`pub struct ASTContext {`
`12`	`14`	`pub filenames: Vec<String>,`
	`15`	`+ /// Counter for example list numbering across the document`
	`16`	`+ /// Example lists continue numbering even when interrupted by other content`
	`17`	`+ pub example_list_counter: Cell<usize>,`
`13`	`18`	`}`
`14`	`19`
`15`	`20`	`impl ASTContext {`
`16`	`21`	`pub fn new() -> Self {`
`17`	`22`	`ASTContext {`
`18`	`23`	`filenames: Vec::new(),`
	`24`	`+ example_list_counter: Cell::new(1),`
`19`	`25`	`}`
`20`	`26`	`}`
`21`	`27`
`22`	`28`	`pub fn with_filename(filename: impl Into<String>) -> Self {`
`23`	`29`	`ASTContext {`
`24`	`30`	`filenames: vec![filename.into()],`
	`31`	`+ example_list_counter: Cell::new(1),`
`25`	`32`	`}`
`26`	`33`	`}`
`27`	`34`
`28`	`35`	`pub fn anonymous() -> Self {`
`29`	`36`	`ASTContext {`
`30`	`37`	`filenames: Vec::new(),`
	`38`	`+ example_list_counter: Cell::new(1),`
`31`	`39`	`}`
`32`	`40`	`}`
`33`	`41`
Original file line number	Diff line number	Diff line change
`@@ -259,7 +259,6 @@ fn transform_definition_list_div(div: Div) -> Block {`
`259`	`259`	`})`
`260`	`260`	`}`
`261`	`261`
`262`		`-`
`263`	`262`	`/// Apply post-processing transformations to the Pandoc AST`
`264`	`263`	`pub fn postprocess(doc: Pandoc) -> Result<Pandoc, Vec<String>> {`
`265`	`264`	`let mut errors = Vec::new();`
Original file line number	Diff line number	Diff line change
`@@ -358,6 +358,7 @@ fn write_list_number_style<T: std::io::Write>(`
`358`	`358`	`crate::pandoc::ListNumberStyle::UpperAlpha => write!(buf, "UpperAlpha"),`
`359`	`359`	`crate::pandoc::ListNumberStyle::LowerRoman => write!(buf, "LowerRoman"),`
`360`	`360`	`crate::pandoc::ListNumberStyle::UpperRoman => write!(buf, "UpperRoman"),`
	`361`	`+ crate::pandoc::ListNumberStyle::Example => write!(buf, "Example"),`
`361`	`362`	`crate::pandoc::ListNumberStyle::Default => write!(buf, "Decimal"), // Is this supposed to be the default?`
`362`	`363`	`}`
`363`	`364`	`}`