Add escape_square_brackets into comment_formats markdown configuration

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to this project will be documented in this file.
 
+## [Next] - YYYY-MM-DD
+
+What's changed
+
+* Add `escape_square_brackets` into `comment_formats` markdown configuration. ([#XXX](...) by lquerel).
+
 ## [0.9.2] - 2024-09-09
 
 What's Changed

crates/weaver_forge/README.md

@@ -579,6 +579,7 @@ comment_formats:           # optional
 
     # Fields specific to 'markdown' format
     escape_backslashes: <bool>            # Whether to escape backslashes in markdown (default: false).
+    escape_square_brackets: <bool>        # Whether to escape square brackets in markdown (default: false).
     shortcut_reference_links: <bool>      # Convert inlined links into shortcut reference links (default: false).
     indent_first_level_list_items: <bool> # Indent the first level of list items in markdown (default: false).
     default_block_code_language: <string> # Default language for block code snippets (default: "").

crates/weaver_forge/src/formats/markdown.rs

@@ -12,10 +12,14 @@ use std::collections::HashMap;
 #[derive(Deserialize, Serialize, Debug, Clone, Default)]
 #[serde(rename_all = "snake_case")]
 pub struct MarkdownRenderOptions {
-    /// Whether to escape backslashes in the markdown.
+    /// Whether to escape backslashes in the Markdown.
     /// Default is false.
     #[serde(default)]
     pub(crate) escape_backslashes: bool,
+    /// Whether to escape square brackets in the Markdown text. Valid links are not affected.
+    /// Default is false.
+    #[serde(default)]
+    pub(crate) escape_square_brackets: bool,
     /// Whether to indent the first level of list items in the markdown.
     /// Default is false.
     #[serde(default)]
@@ -196,11 +200,36 @@ impl MarkdownRenderer {
                 }
             }
             Node::Text(text) => {
+                fn escape_unescaped_chars(s: &str, chars_to_escape: &[char]) -> String {
+                    let mut result = String::with_capacity(s.len());
+                    let mut backslash_count = 0;
+
+                    for c in s.chars() {
+                        if c == '\\' {
+                            backslash_count += 1;
+                            result.push(c);
+                        } else {
+                            if chars_to_escape.contains(&c) && backslash_count % 2 == 0 {
+                                // Even number of backslashes means the character is unescaped
+                                result.push('\\');
+                            }
+                            result.push(c);
+                            // Reset the backslash count after a non-backslash character
+                            backslash_count = 0;
+                        }
+                    }
+
+                    result
+                }
+
+                let mut text = text.value.clone();
                 if options.escape_backslashes {
-                    ctx.add_text(&text.value.replace('\\', "\\\\"));
-                } else {
-                    ctx.add_text(&text.value);
+                    text = text.replace('\\', "\\\\");
+                }
+                if options.escape_square_brackets {
+                    text = escape_unescaped_chars(&text, &['[', ']']);
                 }
+                ctx.add_text(&text);
             }
             Node::Paragraph(p) => {
                 ctx.add_cond_blank_line();
@@ -374,6 +403,7 @@ mod tests {
                         footer: None,
                         format: RenderFormat::Markdown(MarkdownRenderOptions {
                             escape_backslashes: false,
+                            escape_square_brackets: false,
                             indent_first_level_list_items: true,
                             shortcut_reference_link: true,
                             default_block_code_language: None,
@@ -465,6 +495,83 @@ it's RECOMMENDED to:
   - Use a domain-specific attribute
   - Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not."##
         );
+
+        let config = WeaverConfig {
+            comment_formats: Some(
+                vec![(
+                    "go".to_owned(),
+                    CommentFormat {
+                        header: None,
+                        prefix: Some("// ".to_owned()),
+                        footer: None,
+                        format: RenderFormat::Markdown(MarkdownRenderOptions {
+                            escape_backslashes: false,
+                            escape_square_brackets: false,
+                            indent_first_level_list_items: true,
+                            shortcut_reference_link: true,
+                            default_block_code_language: None,
+                        }),
+                        trim: true,
+                        remove_trailing_dots: true,
+                    },
+                )]
+                .into_iter()
+                .collect(),
+            ),
+            default_comment_format: Some("go".to_owned()),
+            ..WeaverConfig::default()
+        };
+
+        let renderer = MarkdownRenderer::try_new(&config)?;
+        let markdown = r##"In some cases a [URL] may refer to an [IP](http://ip.com) and/or port directly,
+          The file \\[extension\\] extracted \\[from] the `url.full`, excluding the leading dot."##;
+        let html = renderer.render(markdown, "go")?;
+        assert_eq!(
+            html,
+            r##"In some cases a [URL] may refer to an [IP] and/or port directly,
+The file \[extension\] extracted \[from] the `url.full`, excluding the leading dot.
+
+[IP]: http://ip.com"##
+        );
+
+        let config = WeaverConfig {
+            comment_formats: Some(
+                vec![(
+                    "go".to_owned(),
+                    CommentFormat {
+                        header: None,
+                        prefix: Some("// ".to_owned()),
+                        footer: None,
+                        format: RenderFormat::Markdown(MarkdownRenderOptions {
+                            escape_backslashes: false,
+                            escape_square_brackets: true,
+                            indent_first_level_list_items: true,
+                            shortcut_reference_link: true,
+                            default_block_code_language: None,
+                        }),
+                        trim: true,
+                        remove_trailing_dots: true,
+                    },
+                )]
+                .into_iter()
+                .collect(),
+            ),
+            default_comment_format: Some("go".to_owned()),
+            ..WeaverConfig::default()
+        };
+
+        let renderer = MarkdownRenderer::try_new(&config)?;
+        let markdown = r##"In some cases a [URL] may refer to an [IP](http://ip.com) and/or port directly,
+          The file \[extension\] extracted \[from] the `url.full`, excluding the leading dot."##;
+        let html = renderer.render(markdown, "go")?;
+        assert_eq!(
+            html,
+            r##"In some cases a \[URL\] may refer to an [IP] and/or port directly,
+The file \[extension\] extracted \[from\] the `url.full`, excluding the leading dot.
+
+[IP]: http://ip.com"##
+        );
+
         Ok(())
     }
 }

docs/weaver-config.md

@@ -52,6 +52,7 @@ comment_formats:           # optional
 
     # The following fields are enabled only when format is set to 'markdown'
     escape_backslashes: <bool>            # Whether to escape backslashes in the markdown (default: false).
+    escape_square_brackets: <bool>        # Whether to escape square brackets in markdown (default: false).
     shortcut_reference_links: <bool>      # Use this to convert inlined links into shortcut reference links, similar to those in Go documentation (default: false).
     indent_first_level_list_items: <bool> # Whether to indent the first level of list items in the markdown (default: false).
     default_block_code_language: <string> # The default language for block code snippets (default: "").