feat: improve templates with new handlebars helper (#9)

* feat: improve templates with new handlebars helper

* chore: update docs

Author: hashemix

docs/guide/helper-functions.md

@@ -37,6 +37,45 @@ Hello, World!
 ─────────────
 ```
 
+### `format_text`
+
+Thu helper is designed to prepare plain or structured text for HTML or Markdown-like rendering. It does the following:
+
+- Replaces line breaks (`\n`) in the input text with a custom line break string (like `<br/>` or an actual newline).
+
+- Wraps inline code snippets—identified by delimiter pairs like <code>\`</code> or `'` — in `<code>` tags for HTML formatting (e.g., turning 'param' into `<code>param</code>`).
+
+This helper is especially useful for formatting capability descriptions in web documentation, markdown previews, or any UI where readable line breaks and inline code styling are needed.
+
+The `code_wrap_chars` parameter (last parameter of the helper function) defines pairs of characters that will wrap inline code blocks and get converted to <code>...</code> in the output.
+
+You must pass a string made up of an even number of characters, where each two characters form one pair:
+
+    The first character is the opening delimiter
+    The last character is the closing delimiter
+
+| Input    | Effect                                 |
+| -------- | -------------------------------------- |
+| `"[]"`   | Matches `[code]` → `<code>code</code>` |
+| `"''"`   | Matches `'code'` → `<code>code</code>` |
+| `"['']"` | Matches both `[code]` and `'code'`     |
+
+Example:
+
+```hbs
+{{format_text "Each entry includes 'name', `type` , and 'children' for directories." "<br>" "'``'" }}
+```
+
+Output text:
+
+```md
+Each entry includes <code>name</code>, <code>type</code> , and <code>children</code> for directories.
+```
+
+Rendered Output:
+
+Each entry includes <code>name</code>, <code>type</code> , and <code>children</code> for directories.
+
 ### `capability`
 
 This helper formats a capability with an optional count and a boolean indicator based on whether the capability is supported.

src/render_template.rs

@@ -67,6 +67,46 @@ pub fn register_helpers(handlebar: &mut Handlebars) {
     // Helper: Adds 1 to an integer value.
     handlebars_helper!(plus_one: |v: i64| format!("{}", v+1));
 
+    // Helper: replaces new line characters with provided `new_line` and optionally wraps tokens enclosed in specified delimiter pairs (like `` or '') with <code> tags.
+    // This can be used to format plain text for HTML or MD display, enabling readable line breaks and inline code styling.
+    handlebars_helper!(format_text: |text: Option<String>, new_line: Option<String>, code_wrap_chars:Option<String> | {
+
+        let text = text.unwrap_or_default();
+
+        let new_line =  new_line.unwrap_or(line_ending(&text, None).to_string());
+
+        let mut replacers = vec![("\\n".to_string(),new_line)];
+
+        if let Some(code_wrap_chars) = code_wrap_chars {
+            // Proceed only if `code_wrap_chars` contains an even number of characters,
+            // so we can pair each starting wrap character with a corresponding ending one.
+            if code_wrap_chars.len() % 2 == 0 {
+                for (left_char, right_char) in code_wrap_chars
+                    .chars()
+                    .take(code_wrap_chars.len() / 2)
+                    .zip(code_wrap_chars.chars().rev())
+                {
+                    replacers.push((
+                        format!(
+                            "{}([\\w\\-\\_]+){}",
+                            regex::escape(&left_char.to_string()),
+                            regex::escape(&right_char.to_string()),
+                        ),
+                        "<code>$1</code>".to_string(),
+                    ));
+                }
+            }
+        }
+
+        let mut result = text;
+        for (regex_str, replace_str) in replacers {
+            let re = Regex::new(&regex_str).unwrap();
+            result = re.replace_all(&result, replace_str).to_string();
+        }
+
+        result
+    });
+
     // Helper: Formats a capability tag with a boolean indicator and optional count.
     handlebars_helper!(capability_tag: |label:Value, supported: Value, count: Option<i64>| {
         let count_str = count.map_or("".to_string(), |count| format!(" ({})", count));
@@ -120,6 +160,7 @@ pub fn register_helpers(handlebar: &mut Handlebars) {
     let helpers: Vec<(&str, Box<dyn HelperDef + Send + Sync>)> = vec![
         ("plus_one", Box::new(plus_one)),
         ("underline", Box::new(underline)),
+        ("format_text", Box::new(format_text)),
         ("capability_tag", Box::new(capability_tag)),
         ("capability", Box::new(capability)),
         ("capability_title", Box::new(capability_title)),

templates/html/html_prompts.hbs

@@ -16,8 +16,7 @@
             <td>
                 <code><b>{{{this.name}}}</b></code>
             </td>
-            <td>{{{replace_regex (replace_regex this.description "'([\\w\\-\\_]+)'" "<code>$1</code>")
-                "\\[([\\w\\-\\_]+)\\]" "<code>$1</code>"}}}</td>
+            <td>{{{format_text this.description "<br/>" "['``']"}}}</td>
         </tr>
         {{/each}}
     </tbody>

templates/html/html_resource_templates.hbs

@@ -20,8 +20,7 @@
             <td>
                 <a>{{this.uriTemplate}} {{#if this.mimeType}}({{{this.mimeType}}}){{/if}}</a>
             </td>
-            <td>{{{replace_regex (replace_regex this.description "'([\\w\\-\\_]+)'" "<code>$1</code>")
-                "\\[([\\w\\-\\_]+)\\]" "<code>$1</code>"}}}</td>
+            <td>{{{format_text this.description "<br/>" "['``']"}}}</td>
         </tr>
         {{/each}}
     </tbody>

templates/html/html_resources.hbs

@@ -20,8 +20,7 @@
             <td>
                 <a>{{this.uri}}</a> {{#if this.mimeType}}<i>({{{this.mimeType}}})</i>{{/if}}
             </td>
-            <td>{{{replace_regex (replace_regex this.description "'([\\w\\-\\_]+)'" "<code>$1</code>")
-                "\\[([\\w\\-\\_]+)\\]" "<code>$1</code>"}}}</td>
+            <td>{{{format_text this.description "<br/>" "['``']"}}}</td>
         </tr>
         {{/each}}
     </tbody>

templates/html/html_tools.hbs

@@ -17,8 +17,7 @@
             <td>
                 <code><b>{{{this.name}}}</b></code>
             </td>
-            <td>{{{replace_regex ( replace_regex (replace_regex this.description "'([\\w\\-\\_]+)'" "<code>$1</code>") "\\n" "<br/>")
-                "\\[([\\w\\-\\_]+)\\]" "<code>$1</code>"}}}</td>
+            <td>{{{format_text this.description "<br/>" "['``']"}}}</td>
             <td>
                 <ul>
                     {{#each this.params}}

templates/markdown/md_plain_prompts.hbs

@@ -5,6 +5,6 @@
     {{#each prompts}}
 
 - **{{{this.name}}}**
-  - {{{replace_regex (replace_regex this.description "'([\\w\\-\\_]+)'" "<code>$1</code>") "\\[([\\w\\-\\_]+)\\]" "<code>$1</code>"}}}
+  - {{{format_text this.description "<br/>" "['``']"}}}
     {{/each}}
 {{/if}}

templates/markdown/md_plain_resource_templates.hbs

@@ -5,7 +5,7 @@
 
 - **{{{this.name}}}**
   {{#if this.description}}
-  - {{{replace_regex (replace_regex this.description "'([\\w\\-\\_]+)'" "<code>$1</code>") "\\[([\\w\\-\\_]+)\\]" "<code>$1</code>"}}}
+  - {{{format_text this.description "<br/>" "['``']"}}}
     {{/if}}
     {{#if this.uri}}
   - URI: <a>{{this.uriTemplate}}</a> {{#if this.mimeType}}<i>({{{this.mimeType}}})</i>{{/if}}

templates/markdown/md_plain_resources.hbs

@@ -5,7 +5,7 @@
 
 - **{{{this.name}}}**
   {{#if this.description}}
-  - {{{replace_regex (replace_regex this.description "'([\\w\\-\\_]+)'" "<code>$1</code>") "\\[([\\w\\-\\_]+)\\]" "<code>$1</code>"}}}{{/if}}
+  - {{{format_text this.description "<br/>" "['``']"}}}{{/if}}
     {{#if this.uri}}
   - URI: <a>{{this.uri}}</a> <i>{{#if this.mimeType}}({{{this.mimeType}}}){{/if}}</i>
     {{/if}}

templates/markdown/md_plain_tools.hbs

@@ -4,7 +4,7 @@
 {{#each tools}}
 
 - **{{{this.name}}}**
-  - {{{replace_regex (replace_regex (replace_regex this.description "'([\\w\\-\\_]+)'" "<code>$1</code>") "\\n" "\n  ") "\\[([\\w\\-\\_]+)\\]" "<code>$1</code>"}}}
+  - {{{format_text this.description "<br/>" "['``']"}}}
   {{#if this.params}}  
   - **Inputs:**
     {{#each this.params}}

templates/markdown/md_prompts.hbs

@@ -16,7 +16,7 @@
             <td>
                 <code><b>{{{this.name}}}</b></code>
             </td>
-            <td>{{{replace_regex (replace_regex this.description "'([\\w\\-\\_]+)'" "<code>$1</code>") "\\[([\\w\\-\\_]+)\\]" "<code>$1</code>"}}}</td>
+            <td>{{{format_text this.description "<br/>" "['``']"}}}</td>
         </tr>
     {{/each}}
 </tbody>

templates/markdown/md_resource_templates.hbs

@@ -20,7 +20,7 @@
             <td>
                 <a>{{this.uriTemplate}}</a> {{#if this.mimeType}}<i>({{{this.mimeType}}})</i>{{/if}}
             </td>
-            <td>{{{replace_regex (replace_regex this.description "'([\\w\\-\\_]+)'" "<code>$1</code>") "\\[([\\w\\-\\_]+)\\]" "<code>$1</code>"}}}</td>
+            <td>{{{format_text this.description "<br/>" "['``']"}}}</td>
         </tr>
     {{/each}}
 </tbody>

templates/markdown/md_resources.hbs

@@ -20,7 +20,7 @@
             <td>
                 <a>{{this.uri}}</a> <i>{{#if this.mimeType}}({{{this.mimeType}}}){{/if}}</i>
             </td>
-            <td>{{{replace_regex (replace_regex this.description "'([\\w\\-\\_]+)'" "<code>$1</code>") "\\[([\\w\\-\\_]+)\\]" "<code>$1</code>"}}}</td>
+            <td>{{{format_text this.description "<br/>" "['``']"}}}</td>
         </tr>
     {{/each}}
 </tbody>

templates/markdown/md_tools.hbs

@@ -17,7 +17,7 @@
             <td>
                 <code><b>{{{this.name}}}</b></code>
             </td>
-            <td>{{{replace_regex (replace_regex (replace_regex this.description "'([\\w\\-\\_]+)'" "<code>$1</code>") "\\n" "\\n  ")"\\[([\\w\\-\\_]+)\\]" "<code>$1</code>"}}}</td>
+            <td>{{{format_text this.description "<br/>" "['``']"}}}</td>
             <td>
                 <ul>
                     {{#each this.params}}

tests/fixtures/cmds.txt

@@ -1,23 +1,8 @@
-# create md-create.md
 ./mcp-discovery create -f ../../tests/fixtures/md-create.md -- npx -y @modelcontextprotocol/server-everything
-
-# create md-create.md
 ./mcp-discovery create -f ../../tests/fixtures/md-plain-create.md --template md-plain -- npx -y @modelcontextprotocol/server-everything
-
-# create txt-create.txt
 ./mcp-discovery create -f ../../tests/fixtures/txt-create.txt --template txt -- npx -y @modelcontextprotocol/server-everything
-
-# full update md-update.md
 ./mcp-discovery update -f ../../tests/fixtures/md-update.md  -- npx -y @modelcontextprotocol/server-everything
-
-# full update md-plain-update.md
 ./mcp-discovery update -f ../../tests/fixtures/md-plain-update.md -t md-plain  -- npx -y @modelcontextprotocol/server-everything
-
-#  md-plain-update-file-prop.md
 ./mcp-discovery update -f ../../tests/fixtures/md-plain-update-file-prop.md -- npx -y @modelcontextprotocol/server-everything
-
-# md-plain-update-template-prop.md
 ./mcp-discovery update -f ../../tests/fixtures/md-plain-update-template-prop.md -- npx -y @modelcontextprotocol/server-everything
-
-# md-plain-update-inline.md
 ./mcp-discovery update -f ../../tests/fixtures/md-plain-update-inline.md -- npx -y @modelcontextprotocol/server-everything