fix(rules): support multi-line code spans in MkDocs containers

Replace the per-line backtick scanner with a dedent-and-reparse approach
that delegates all CommonMark parsing to pulldown-cmark. This handles
multi-line code spans natively without manual reimplementation of
CommonMark edge cases.

The approach: identify contiguous runs of MkDocs container lines, strip
the container indentation, reparse with pulldown-cmark, then map byte
offsets back to the original document. Container openers (admonition
markers, tab markers) are excluded from the minimum indent calculation
so nested containers (e.g., admonition inside content tab) are handled
correctly.

Also fix MD034 and MD052 code span filters to use byte-offset
comparison instead of single-line-only line/column checks, which
correctly handles multi-line code spans for both URL and email detection.

Author: rvben

src/lint_context/element_parsers.rs

@@ -1,5 +1,7 @@
 use crate::config::MarkdownFlavor;
 use crate::utils::code_block_utils::CodeBlockUtils;
+use crate::utils::mkdocs_admonitions;
+use crate::utils::mkdocs_tabs;
 use crate::utils::regex_cache::URL_SIMPLE_REGEX;
 use pulldown_cmark::{Event, Options, Parser};
 use regex::Regex;
@@ -11,7 +13,11 @@ use super::types::*;
 static BARE_EMAIL_PATTERN: LazyLock<Regex> =
     LazyLock::new(|| Regex::new(r"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}").unwrap());
 
-/// Parse all inline code spans in the content using pulldown-cmark streaming parser
+/// Parse all inline code spans in the content using pulldown-cmark streaming parser.
+///
+/// Note: For MkDocs content, `scan_mkdocs_container_code_spans()` must be called separately
+/// to detect code spans that pulldown-cmark misses inside 4-space-indented containers.
+/// This is done during LintContext construction in mod.rs.
 pub(super) fn parse_code_spans(content: &str, lines: &[LineInfo]) -> Vec<CodeSpan> {
     // Quick check - if no backticks, no code spans
     if !content.contains('`') {
@@ -31,6 +37,119 @@ pub(super) fn parse_code_spans(content: &str, lines: &[LineInfo]) -> Vec<CodeSpa
     build_code_spans_from_ranges(content, lines, &ranges)
 }
 
+/// Scan MkDocs container lines for code spans that pulldown-cmark missed.
+///
+/// pulldown-cmark treats 4-space-indented MkDocs content (admonitions, content tabs,
+/// markdown HTML blocks) as indented code blocks, so it never emits `Event::Code` for
+/// backtick spans within those regions. This function dedents contiguous runs of container
+/// lines and reparses them with pulldown-cmark, which correctly handles both single-line
+/// and multi-line code spans including all CommonMark edge cases.
+pub(super) fn scan_mkdocs_container_code_spans(
+    content: &str,
+    lines: &[LineInfo],
+    existing_ranges: &[(usize, usize)],
+) -> Vec<CodeSpan> {
+    let mut extra_ranges: Vec<(usize, usize)> = Vec::new();
+
+    // Process contiguous runs of MkDocs container lines
+    let mut i = 0;
+    while i < lines.len() {
+        // Find start of a container run
+        if !lines[i].in_mkdocs_container() || lines[i].in_code_block {
+            i += 1;
+            continue;
+        }
+
+        // Collect the contiguous run
+        let run_start = i;
+        while i < lines.len() && lines[i].in_mkdocs_container() && !lines[i].in_code_block {
+            i += 1;
+        }
+        let run_end = i;
+
+        // Quick check: any backticks in this run?
+        let has_backticks = lines[run_start..run_end]
+            .iter()
+            .any(|li| li.content(content).contains('`'));
+        if !has_backticks {
+            continue;
+        }
+
+        // Compute minimum indentation across content lines only.
+        // Container openers (e.g., `=== "Tab"`, `!!! note`) are structural markers
+        // that should be excluded from the min_indent calculation. For nested
+        // containers (admonition inside content tab), including openers would
+        // prevent stripping enough indent from deeply nested content, causing
+        // pulldown-cmark to misinterpret it as indented code blocks.
+        let min_indent = lines[run_start..run_end]
+            .iter()
+            .filter(|li| {
+                if li.is_blank || li.indent == 0 {
+                    return false;
+                }
+                let line_text = li.content(content);
+                // Exclude container openers from min_indent calculation
+                if mkdocs_admonitions::is_admonition_start(line_text) || mkdocs_tabs::is_tab_marker(line_text) {
+                    return false;
+                }
+                true
+            })
+            .map(|li| li.indent)
+            .min()
+            .unwrap_or(0);
+
+        // Build dedented string and line map for offset translation.
+        // Each entry: (byte offset in dedented string, byte offset in original document)
+        let mut dedented = String::new();
+        let mut line_map: Vec<(usize, usize)> = Vec::new();
+
+        for li in &lines[run_start..run_end] {
+            let dedented_line_start = dedented.len();
+            let line_content = li.content(content);
+            let bytes_to_strip = min_indent.min(li.indent);
+            let stripped = &line_content[bytes_to_strip..];
+            let original_start = li.byte_offset + bytes_to_strip;
+            line_map.push((dedented_line_start, original_start));
+            dedented.push_str(stripped);
+            dedented.push('\n');
+        }
+
+        // Parse the dedented string with pulldown-cmark
+        let parser = Parser::new(&dedented).into_offset_iter();
+        for (event, range) in parser {
+            if let Event::Code(_) = event {
+                let orig_start = dedented_to_original(range.start, &line_map);
+                let orig_end = dedented_to_original(range.end, &line_map);
+
+                // Skip ranges already detected by the initial pulldown-cmark pass
+                let overlaps = existing_ranges.iter().any(|&(s, e)| s < orig_end && e > orig_start);
+                if !overlaps {
+                    extra_ranges.push((orig_start, orig_end));
+                }
+            }
+        }
+    }
+
+    if extra_ranges.is_empty() {
+        return Vec::new();
+    }
+
+    extra_ranges.sort_unstable_by_key(|&(start, _)| start);
+    build_code_spans_from_ranges(content, lines, &extra_ranges)
+}
+
+/// Convert a byte offset in the dedented string back to the original document offset.
+///
+/// `line_map` entries are `(dedented_line_start, original_line_start)`.
+fn dedented_to_original(dedented_offset: usize, line_map: &[(usize, usize)]) -> usize {
+    // Find the rightmost entry whose dedented_line_start <= dedented_offset
+    let idx = line_map
+        .partition_point(|&(ds, _)| ds <= dedented_offset)
+        .saturating_sub(1);
+    let (dedented_line_start, original_line_start) = line_map[idx];
+    original_line_start + (dedented_offset - dedented_line_start)
+}
+
 pub(super) fn build_code_spans_from_ranges(
     content: &str,
     lines: &[LineInfo],

src/lint_context/mod.rs

@@ -294,12 +294,27 @@ impl<'a> LintContext<'a> {
         }
 
         // Parse code spans early so we can exclude them from link/image parsing
-        let code_spans = profile_section!(
+        let mut code_spans = profile_section!(
             "Code spans",
             profile,
             element_parsers::build_code_spans_from_ranges(content, &lines, &code_span_ranges)
         );
 
+        // Supplement code spans for MkDocs container content that pulldown-cmark missed.
+        // pulldown-cmark treats 4-space-indented MkDocs content as indented code blocks,
+        // so backtick code spans within admonitions/tabs/markdown HTML are invisible to it.
+        if flavor == MarkdownFlavor::MkDocs {
+            let extra = profile_section!(
+                "MkDocs code spans",
+                profile,
+                element_parsers::scan_mkdocs_container_code_spans(content, &lines, &code_span_ranges,)
+            );
+            if !extra.is_empty() {
+                code_spans.extend(extra);
+                code_spans.sort_by_key(|span| span.byte_offset);
+            }
+        }
+
         // Mark lines that are continuations of multi-line code spans
         // This is needed for parse_list_blocks to correctly handle list items with multi-line code spans
         for span in &code_spans {

src/rules/md034_no_bare_urls.rs

@@ -392,10 +392,10 @@ impl MD034NoBareUrls {
                         continue;
                     }
 
-                    // Check if email is inside a code span
+                    // Check if email is inside a code span (byte offsets handle multi-line spans)
                     let is_in_code_span = code_spans
                         .iter()
-                        .any(|span| span.line == line_number && start >= span.start_col && start < span.end_col);
+                        .any(|span| absolute_pos >= span.byte_offset && absolute_pos < span.byte_end);
 
                     if !is_in_code_span {
                         let email_len = end - start;
@@ -485,14 +485,19 @@ impl Rule for MD034NoBareUrls {
             let mut line_warnings =
                 self.check_line(line.content, ctx, line.line_num, &code_spans, &mut buffers, line_index);
 
-            // Filter out warnings that are inside code spans
+            // Filter out warnings that are inside code spans (handles multi-line spans via byte offsets)
             line_warnings.retain(|warning| {
-                // Check if the URL is inside a code span
                 !code_spans.iter().any(|span| {
-                    span.line == warning.line &&
-                    warning.column > 0 && // column is 1-indexed
-                    (warning.column - 1) >= span.start_col &&
-                    (warning.column - 1) < span.end_col
+                    if let Some(fix) = &warning.fix {
+                        // Byte-offset check handles both single-line and multi-line code spans
+                        fix.range.start >= span.byte_offset && fix.range.start < span.byte_end
+                    } else {
+                        span.line == warning.line
+                            && span.end_line == warning.line
+                            && warning.column > 0
+                            && (warning.column - 1) >= span.start_col
+                            && (warning.column - 1) < span.end_col
+                    }
                 })
             });
 

src/rules/md052_reference_links_images.rs

@@ -262,11 +262,11 @@ impl MD052ReferenceLinkImages {
         false
     }
 
-    /// Check if a position is inside any code span
-    fn is_in_code_span(line: usize, col: usize, code_spans: &[crate::lint_context::CodeSpan]) -> bool {
+    /// Check if a byte position is inside any code span
+    fn is_in_code_span(byte_pos: usize, code_spans: &[crate::lint_context::CodeSpan]) -> bool {
         code_spans
             .iter()
-            .any(|span| span.line == line && col >= span.start_col && col < span.end_col)
+            .any(|span| byte_pos >= span.byte_offset && byte_pos < span.byte_end)
     }
 
     /// Check if a byte position is within an HTML tag
@@ -340,7 +340,7 @@ impl MD052ReferenceLinkImages {
             }
 
             // Skip links inside code spans
-            if Self::is_in_code_span(link.line, link.start_col, &code_spans) {
+            if Self::is_in_code_span(link.byte_offset, &code_spans) {
                 continue;
             }
 
@@ -447,7 +447,7 @@ impl MD052ReferenceLinkImages {
             }
 
             // Skip images inside code spans
-            if Self::is_in_code_span(image.line, image.start_col, &code_spans) {
+            if Self::is_in_code_span(image.byte_offset, &code_spans) {
                 continue;
             }
 
@@ -709,17 +709,15 @@ impl MD052ReferenceLinkImages {
                         if !references.contains(&reference_lower) && !reported_refs.contains_key(&reference_lower) {
                             let full_match = cap.get(0).unwrap();
                             let col = full_match.start();
+                            let line_start_byte = ctx.line_offsets[line_num];
+                            let byte_pos = line_start_byte + col;
 
                             // Skip if inside code span
                             let code_spans = ctx.code_spans();
-                            if Self::is_in_code_span(line_num + 1, col, &code_spans) {
+                            if Self::is_in_code_span(byte_pos, &code_spans) {
                                 continue;
                             }
 
-                            // Check if this position is within a covered range
-                            let line_start_byte = ctx.line_offsets[line_num];
-                            let byte_pos = line_start_byte + col;
-
                             // Skip if inside Jinja template
                             if ctx.is_in_jinja_range(byte_pos) {
                                 continue;