Add path annotation for codeblock

components/markdown/src/codeblock/fence.rs

@@ -24,6 +24,7 @@ pub struct FenceSettings<'a> {
     pub line_number_start: usize,
     pub highlight_lines: Vec<RangeInclusive<usize>>,
     pub hide_lines: Vec<RangeInclusive<usize>>,
+    pub name: Option<&'a str>,
 }
 
 impl<'a> FenceSettings<'a> {
@@ -34,6 +35,7 @@ impl<'a> FenceSettings<'a> {
             line_number_start: 1,
             highlight_lines: Vec::new(),
             hide_lines: Vec::new(),
+            name: None,
         };
 
         for token in FenceIter::new(fence_info) {
@@ -43,6 +45,7 @@ impl<'a> FenceSettings<'a> {
                 FenceToken::InitialLineNumber(l) => me.line_number_start = l,
                 FenceToken::HighlightLines(lines) => me.highlight_lines.extend(lines),
                 FenceToken::HideLines(lines) => me.hide_lines.extend(lines),
+                FenceToken::Name(n) => me.name = Some(n),
             }
         }
 
@@ -57,6 +60,7 @@ enum FenceToken<'a> {
     InitialLineNumber(usize),
     HighlightLines(Vec<RangeInclusive<usize>>),
     HideLines(Vec<RangeInclusive<usize>>),
+    Name(&'a str),
 }
 
 struct FenceIter<'a> {
@@ -103,7 +107,16 @@ impl<'a> Iterator for FenceIter<'a> {
                     let ranges = Self::parse_ranges(tok_split.next());
                     return Some(FenceToken::HideLines(ranges));
                 }
+                "name" => {
+                    if let Some(n) = tok_split.next() {
+                        return Some(FenceToken::Name(n));
+                    }
+                }
                 lang => {
+                    if tok_split.next().is_some() {
+                        eprintln!("Warning: Unknown annotation {}", lang);
+                        continue;
+                    }
                     return Some(FenceToken::Language(lang));
                 }
             }

components/markdown/src/codeblock/mod.rs

@@ -12,6 +12,7 @@ pub(crate) use fence::FenceSettings;
 
 fn opening_html(
     language: Option<&str>,
+    name: Option<&str>,
     pre_style: Option<String>,
     pre_class: Option<String>,
     line_numbers: bool,
@@ -32,6 +33,12 @@ fn opening_html(
         html.push('"');
     }
 
+    if let Some(name) = name {
+        html.push_str(" data-name=\"");
+        html.push_str(name);
+        html.push('"');
+    }
+
     if let Some(styles) = pre_style {
         html.push_str(" style=\"");
         html.push_str(styles.as_str());
@@ -56,6 +63,12 @@ fn opening_html(
         html.push_str(lang);
         html.push('"');
     }
+
+    if let Some(name) = name {
+        html.push_str(" data-name=\"");
+        html.push_str(name);
+        html.push('"');
+    }
     html.push('>');
     html
 }
@@ -89,6 +102,7 @@ impl<'config> CodeBlock<'config> {
 
         let html_start = opening_html(
             fence.language,
+            fence.name,
             highlighter.pre_style(),
             highlighter.pre_class(),
             fence.line_numbers,

docs/content/documentation/content/syntax-highlighting.md

@@ -302,7 +302,7 @@ highlight(code);
 
 - `hide_lines` to hide lines. You must specify a list of inclusive ranges of lines to hide,
 separated by ` ` (whitespace). Ranges are 1-indexed.
-  
+
 ````
 ```rust,hide_lines=1-2
 use highlighter::highlight;
@@ -311,6 +311,16 @@ highlight(code);
 ```
 ````
 
+- `name` to specify a name the code block is associated with.
+
+````
+```rust,name=mod.rs
+use highlighter::highlight;
+let code = "...";
+highlight(code);
+```
+````
+
 ## Styling codeblocks
 
 Depending on the annotations used, some codeblocks will be hard to read without any CSS. We recommend using the following