gitlab-glfm-markdown 0.0.34-x86_64-darwin → 0.0.35-x86_64-darwin

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d44ed632f02ab1f68d423c7484cee9b6f15c1d925f90494b8eb0593da3ec83d5
-  data.tar.gz: dd7b68dd0b730c552f56d3ad39d2926aef3261c9093e212ab6fdf76c449e04b4
+  metadata.gz: 8abca4c916fb32f1fdd737a162d9f1e320de2354c7c8c6bcd58da5abd1d8b636
+  data.tar.gz: 3b8c0a5795808546505ed3dfe5de19b909a24d98deb8f8c069663904067f50ca
 SHA512:
-  metadata.gz: ad511a2859c548337bdc2e88f3159bec6eccbbe254e53901d99a64bb828a497e8db333c19f1ef3a5d6d2319bd502d13eadcb6af72fce7ab17729df69a939e775
-  data.tar.gz: ee007658a9f16ab00968a10101a6ad4bf5487c2c4f64e22f4a19836c3808e820c0c4705e4f17348a74350515cfef2d508015cf7f6a35feebcca65d7f9d663700
+  metadata.gz: c6b0e1f98cb9b113f3744ae8315a9c94b5de95894fddf3d447379e6c226eb3d067fb661c9c590e0aa3ecf4d2ae261520a390795111c00ce75d136a4e4c6c40d9
+  data.tar.gz: 1e889571a094af135aeb03ed9ce95a500d2ae5bd308094cad6e99e7af5d9cbbeda9b75b8388efbeb6bc1b39df73d05d79690d0a438d9a046d5f3e6e38efba8b3

data/Cargo.lock

@@ -227,9 +227,9 @@ checksum = "b05b61dc5112cbb17e4b6cd61790d9845d13888356391624cbe7e41efeac1e75"
 
 [[package]]
 name = "comrak"
-version = "0.41.1"
+version = "0.43.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9a45df55bc7f91b899160098a7c9b35d6e575dfb4fe22100f014b41a171af2c6"
+checksum = "5ccfd7678fba9aff54a74a70352d952b345e568823ed9d5a92ebc8ad0adad8ea"
 dependencies = [
  "caseless",
  "emojis",
@@ -320,7 +320,7 @@ checksum = "3f9eec918d3f24069decb9af1554cad7c880e2da24a9afd88aca000531ab82c1"
 
 [[package]]
 name = "glfm_markdown"
-version = "0.0.34"
+version = "0.0.35"
 dependencies = [
  "clap",
  "comrak",
@@ -328,6 +328,8 @@ dependencies = [
  "magnus",
  "rb-sys",
  "regex",
+ "serde",
+ "serde_magnus",
 ]
 
 [[package]]
@@ -707,6 +709,17 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "serde_magnus"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "76c20da583b5e1016e9199ef5f3260f7a8d1b253307d232600f6b12737262dbd"
+dependencies = [
+ "magnus",
+ "serde",
+ "tap",
+]
+
 [[package]]
 name = "shell-words"
 version = "1.1.0"
@@ -775,6 +788,12 @@ dependencies = [
  "yaml-rust",
 ]
 
+[[package]]
+name = "tap"
+version = "1.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "55937e1799185b12863d447f42597ed69d9928686b8d88a1df17376a097d8369"
+
 [[package]]
 name = "thiserror"
 version = "1.0.69"

data/README.md

@@ -5,7 +5,7 @@
 
 Implements GLFM (as used by GitLab) using the Rust-based markdown parser [comrak](https://github.com/kivikakk/comrak)
 and providing a Ruby interface.\
-_Currently using `comrak 0.41.1`_.
+_Currently using `comrak 0.43.0`_.
 
 This project is still in constant flux, so interfaces and functionality can change at any time.
 
@@ -27,6 +27,8 @@ Try on command line:
 rake compile
 bin/console
 
+require 'glfm_markdown'
+
 GLFMMarkdown.to_html('# header', options: { sourcepos: true })
 ```
 

data/ext/glfm_markdown/Cargo.lock

@@ -227,9 +227,9 @@ checksum = "b05b61dc5112cbb17e4b6cd61790d9845d13888356391624cbe7e41efeac1e75"
 
 [[package]]
 name = "comrak"
-version = "0.41.1"
+version = "0.43.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9a45df55bc7f91b899160098a7c9b35d6e575dfb4fe22100f014b41a171af2c6"
+checksum = "5ccfd7678fba9aff54a74a70352d952b345e568823ed9d5a92ebc8ad0adad8ea"
 dependencies = [
  "caseless",
  "emojis",
@@ -320,7 +320,7 @@ checksum = "3f9eec918d3f24069decb9af1554cad7c880e2da24a9afd88aca000531ab82c1"
 
 [[package]]
 name = "glfm_markdown"
-version = "0.0.34"
+version = "0.0.35"
 dependencies = [
  "clap",
  "comrak",
@@ -328,6 +328,8 @@ dependencies = [
  "magnus",
  "rb-sys",
  "regex",
+ "serde",
+ "serde_magnus",
 ]
 
 [[package]]
@@ -707,6 +709,17 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "serde_magnus"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "76c20da583b5e1016e9199ef5f3260f7a8d1b253307d232600f6b12737262dbd"
+dependencies = [
+ "magnus",
+ "serde",
+ "tap",
+]
+
 [[package]]
 name = "shell-words"
 version = "1.1.0"
@@ -775,6 +788,12 @@ dependencies = [
  "yaml-rust",
 ]
 
+[[package]]
+name = "tap"
+version = "1.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "55937e1799185b12863d447f42597ed69d9928686b8d88a1df17376a097d8369"
+
 [[package]]
 name = "thiserror"
 version = "1.0.69"

data/ext/glfm_markdown/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "glfm_markdown"
-version = "0.0.34"
+version = "0.0.35"
 edition = "2021"
 authors = ["digitalmoksha <bwalker@gitlab.com>", "Asherah Connor <aconnor@gitlab.com>"]
 description = "GitLab Flavored Markdown parser and formatter. 100% CommonMark-compatible. Experimental."
@@ -15,11 +15,13 @@ required-features = ["cli"]
 
 [dependencies]
 clap = { version = "=4.4.18", optional = true, features = ["derive", "string"] }
-comrak = { version = "0.41.1", default-features = false, features = ["shortcodes"] }
+comrak = { version = "0.43.0", default-features = false, features = ["shortcodes"] }
 magnus = "0.6.2"
 rb-sys = { version = "0.9.86", default-features = false, features = ["stable-api-compiled-fallback"] }
 regex = "1.11.1"
 lazy_static = "1.5.0"
+serde_magnus = "0.8.1"
+serde = { version = "1.0.219", features = ["serde_derive"] }
 
 [features]
 cli = ["clap", "comrak/syntect"]

data/ext/glfm_markdown/src/formatter.rs

@@ -0,0 +1,408 @@
+use std::fmt::{self, Write};
+
+use comrak::html::{collect_text, format_node_default, render_sourcepos, ChildRendering, Context};
+use comrak::nodes::{AstNode, ListType, NodeValue};
+use comrak::{create_formatter, html};
+use lazy_static::lazy_static;
+use regex::Regex;
+
+// TODO: Use std::sync:LazyLock once we're on 1.80+.
+// https://doc.rust-lang.org/std/sync/struct.LazyLock.html
+lazy_static! {
+    static ref PLACEHOLDER_REGEX: Regex = Regex::new(r"%(\{|%7B)(\w{1,30})(}|%7D)").unwrap();
+}
+
+pub struct RenderUserData {
+    pub default_html: bool,
+    pub inapplicable_tasks: bool,
+    pub placeholder_detection: bool,
+    pub only_escape_chars: Option<Vec<char>>,
+    pub debug: bool,
+}
+
+// The important thing to remember is that this overrides the default behavior of the
+// specified nodes. If we do override a node, then it's our responsibility to ensure that
+// any changes in the `comrak` code for those nodes is backported to here, such as when
+// `figcaption` support was added.
+// One idea to limit that would be having the ability to specify attributes that would
+// be inserted when a node is rendered. That would allow us to (in many cases) just
+// inject the changes we need. Such a feature would need to be added to `comrak`.
+create_formatter!(CustomFormatter<RenderUserData>, {
+    NodeValue::Text(_) => |context, node, entering| {
+        return render_text(context, node, entering);
+    },
+    NodeValue::Link(_) => |context, node, entering| {
+        return render_link(context, node, entering);
+    },
+    NodeValue::Image(_) => |context, node, entering| {
+        return render_image(context, node, entering);
+    },
+    NodeValue::List(_) => |context, node, entering| {
+        return render_list(context, node, entering);
+    },
+    NodeValue::TaskItem(_) => |context, node, entering| {
+        return render_task_item(context, node, entering);
+    },
+    NodeValue::Heading(_) => |context, node, entering| {
+        return render_heading(context, node, entering);
+    },
+    NodeValue::Escaped => |context, node, entering| {
+        return render_escaped(context, node, entering);
+    },
+});
+
+fn render_image<'a>(
+    context: &mut Context<RenderUserData>,
+    node: &'a AstNode<'a>,
+    entering: bool,
+) -> Result<ChildRendering, fmt::Error> {
+    let NodeValue::Image(ref nl) = node.data.borrow().value else {
+        unreachable!()
+    };
+
+    if !(context.user.placeholder_detection && PLACEHOLDER_REGEX.is_match(&nl.url)) {
+        return html::format_node_default(context, node, entering);
+    }
+
+    if entering {
+        if context.options.render.figure_with_caption {
+            context.write_str("<figure>")?;
+        }
+        context.write_str("<img")?;
+        html::render_sourcepos(context, node)?;
+        context.write_str(" src=\"")?;
+        if context.options.render.unsafe_ || !html::dangerous_url(&nl.url) {
+            if let Some(rewriter) = &context.options.extension.image_url_rewriter {
+                context.escape_href(&rewriter.to_html(&nl.url))?;
+            } else {
+                context.escape_href(&nl.url)?;
+            }
+        }
+
+        context.write_str("\"")?;
+
+        if PLACEHOLDER_REGEX.is_match(&nl.url) {
+            context.write_str(" data-placeholder")?;
+        }
+
+        context.write_str(" alt=\"")?;
+
+        return Ok(ChildRendering::Plain);
+    } else {
+        if !nl.title.is_empty() {
+            context.write_str("\" title=\"")?;
+            context.escape(&nl.title)?;
+        }
+        context.write_str("\" />")?;
+        if context.options.render.figure_with_caption {
+            if !nl.title.is_empty() {
+                context.write_str("<figcaption>")?;
+                context.escape(&nl.title)?;
+                context.write_str("</figcaption>")?;
+            }
+            context.write_str("</figure>")?;
+        };
+    }
+
+    Ok(ChildRendering::HTML)
+}
+
+fn render_link<'a>(
+    context: &mut Context<RenderUserData>,
+    node: &'a AstNode<'a>,
+    entering: bool,
+) -> Result<ChildRendering, fmt::Error> {
+    let NodeValue::Link(ref nl) = node.data.borrow().value else {
+        unreachable!()
+    };
+
+    if !(context.user.placeholder_detection && PLACEHOLDER_REGEX.is_match(&nl.url)) {
+        return html::format_node_default(context, node, entering);
+    }
+
+    let parent_node = node.parent();
+
+    if !context.options.parse.relaxed_autolinks
+        || (parent_node.is_none()
+            || !matches!(
+                parent_node.unwrap().data.borrow().value,
+                NodeValue::Link(..)
+            ))
+    {
+        if entering {
+            context.write_str("<a")?;
+            html::render_sourcepos(context, node)?;
+            context.write_str(" href=\"")?;
+            if context.options.render.unsafe_ || !html::dangerous_url(&nl.url) {
+                if let Some(rewriter) = &context.options.extension.link_url_rewriter {
+                    context.escape_href(&rewriter.to_html(&nl.url))?;
+                } else {
+                    context.escape_href(&nl.url)?;
+                }
+            }
+            context.write_str("\"")?;
+
+            if !nl.title.is_empty() {
+                context.write_str(" title=\"")?;
+                context.escape(&nl.title)?;
+            }
+
+            if PLACEHOLDER_REGEX.is_match(&nl.url) {
+                context.write_str(" data-placeholder")?;
+            }
+
+            context.write_str(">")?;
+        } else {
+            context.write_str("</a>")?;
+        }
+    }
+
+    Ok(ChildRendering::HTML)
+}
+
+// Overridden to use class `task-list` instead of `contains-task-list`
+// to align with GitLab class usage
+fn render_list<'a>(
+    context: &mut Context<RenderUserData>,
+    node: &'a AstNode<'a>,
+    entering: bool,
+) -> Result<ChildRendering, fmt::Error> {
+    if !entering || !context.options.render.tasklist_classes {
+        return html::format_node_default(context, node, entering);
+    }
+
+    let NodeValue::List(ref nl) = node.data.borrow().value else {
+        unreachable!()
+    };
+
+    context.cr()?;
+    match nl.list_type {
+        ListType::Bullet => {
+            context.write_str("<ul")?;
+            if nl.is_task_list {
+                context.write_str(" class=\"task-list\"")?;
+            }
+            html::render_sourcepos(context, node)?;
+            context.write_str(">\n")?;
+        }
+        ListType::Ordered => {
+            context.write_str("<ol")?;
+            if nl.is_task_list {
+                context.write_str(" class=\"task-list\"")?;
+            }
+            html::render_sourcepos(context, node)?;
+            if nl.start == 1 {
+                context.write_str(">\n")?;
+            } else {
+                writeln!(context, " start=\"{}\">", nl.start)?;
+            }
+        }
+    }
+
+    Ok(ChildRendering::HTML)
+}
+
+// Overridden to detect inapplicable task list items
+fn render_task_item<'a>(
+    context: &mut Context<RenderUserData>,
+    node: &'a AstNode<'a>,
+    entering: bool,
+) -> Result<ChildRendering, fmt::Error> {
+    if !context.user.inapplicable_tasks {
+        return html::format_node_default(context, node, entering);
+    }
+
+    let NodeValue::TaskItem(symbol) = node.data.borrow().value else {
+        unreachable!()
+    };
+
+    if symbol.is_none() || matches!(symbol, Some('x' | 'X')) {
+        return html::format_node_default(context, node, entering);
+    }
+
+    if entering {
+        // Handle an inapplicable task symbol.
+        if matches!(symbol, Some('~')) {
+            context.cr()?;
+            context.write_str("<li")?;
+            context.write_str(" class=\"inapplicable")?;
+
+            if context.options.render.tasklist_classes {
+                context.write_str(" task-list-item")?;
+            }
+            context.write_str("\"")?;
+
+            html::render_sourcepos(context, node)?;
+            context.write_str(">")?;
+            context.write_str("<input type=\"checkbox\"")?;
+
+            if context.options.render.tasklist_classes {
+                context.write_str(" class=\"task-list-item-checkbox\"")?;
+            }
+
+            context.write_str(" data-inapplicable disabled=\"\"> ")?;
+        } else {
+            // Don't allow unsupported symbols to render a checkbox
+            context.cr()?;
+            context.write_str("<li")?;
+
+            if context.options.render.tasklist_classes {
+                context.write_str(" class=\"task-list-item\"")?;
+            }
+
+            html::render_sourcepos(context, node)?;
+            context.write_str(">")?;
+            context.write_str("[")?;
+            context.escape(&symbol.unwrap().to_string())?;
+            context.write_str("] ")?;
+        }
+    } else {
+        context.write_str("</li>\n")?;
+    }
+
+    Ok(ChildRendering::HTML)
+}
+
+fn render_text<'a>(
+    context: &mut Context<RenderUserData>,
+    node: &'a AstNode<'a>,
+    entering: bool,
+) -> Result<ChildRendering, fmt::Error> {
+    let NodeValue::Text(ref literal) = node.data.borrow().value else {
+        unreachable!()
+    };
+
+    if !(context.user.placeholder_detection && PLACEHOLDER_REGEX.is_match(literal)) {
+        return html::format_node_default(context, node, entering);
+    }
+
+    // Don't currently support placeholders in the text inside links or images.
+    // If the text has an underscore in it, then the parser will not combine
+    // the multiple text nodes in `comrak`'s `postprocess_text_nodes`, breaking up
+    // the placeholder into multiple text nodes.
+    // For example, `[%{a_b}](link)`.
+    let parent = node.parent().unwrap();
+    if matches!(
+        parent.data.borrow().value,
+        NodeValue::Link(_) | NodeValue::Image(_)
+    ) {
+        return html::format_node_default(context, node, entering);
+    }
+
+    if entering {
+        let mut cursor: usize = 0;
+
+        for mat in PLACEHOLDER_REGEX.find_iter(literal) {
+            if mat.start() > cursor {
+                context.escape(&literal[cursor..mat.start()])?;
+            }
+
+            context.write_str("<span data-placeholder>")?;
+            context.escape(&literal[mat.start()..mat.end()])?;
+            context.write_str("</span>")?;
+
+            cursor = mat.end();
+        }
+
+        if cursor < literal.len() {
+            context.escape(&literal[cursor..literal.len()])?;
+        }
+    }
+
+    Ok(ChildRendering::HTML)
+}
+
+fn render_heading<'a>(
+    context: &mut Context<RenderUserData>,
+    node: &'a AstNode<'a>,
+    entering: bool,
+) -> Result<ChildRendering, fmt::Error> {
+    let NodeValue::Heading(ref nh) = node.data.borrow().value else {
+        unreachable!()
+    };
+
+    match context.plugins.render.heading_adapter {
+        None => {
+            // Overrides the default handling in order to render the heading text
+            // inside the anchor tag to better support screen readers
+            if entering {
+                context.cr()?;
+                write!(context, "<h{}", nh.level)?;
+                render_sourcepos(context, node)?;
+                context.write_str(">")?;
+
+                if let Some(ref prefix) = context.options.extension.header_ids {
+                    let text_content = collect_text(node);
+                    let id = context.anchorizer.anchorize(&text_content);
+                    write!(
+                        context,
+                        r##"<a href="#{id}" class="anchor" id="{prefix}{id}">"##
+                    )?;
+                }
+            } else {
+                if context.options.extension.header_ids.is_some() {
+                    write!(context, "</a>")?;
+                }
+                writeln!(context, "</h{}>", nh.level)?;
+            }
+            Ok(ChildRendering::HTML)
+        }
+        Some(_adapter) => format_node_default(context, node, entering),
+    }
+}
+
+fn render_escaped<'a>(
+    context: &mut Context<RenderUserData>,
+    node: &'a AstNode<'a>,
+    entering: bool,
+) -> Result<ChildRendering, fmt::Error> {
+    if !context.options.render.escaped_char_spans {
+        return Ok(ChildRendering::HTML);
+    }
+
+    if context.user.only_escape_chars.is_none()
+        || with_node_text_content(node, false, |content| {
+            if content.len() != 1 {
+                return false;
+            }
+            let c = content.chars().next().unwrap();
+            context
+                .user
+                .only_escape_chars
+                .as_ref()
+                .unwrap()
+                .contains(&c)
+        })
+    {
+        if entering {
+            context.write_str("<span data-escaped-char")?;
+            render_sourcepos(context, node)?;
+            context.write_str(">")?;
+        } else {
+            context.write_str("</span>")?;
+        }
+    }
+
+    Ok(ChildRendering::HTML)
+}
+
+/// If the given node has a single text child, apply a function to the text content
+/// of that node. Otherwise, return the given default value.
+fn with_node_text_content<'a, U, F>(node: &'a AstNode<'a>, default: U, f: F) -> U
+where
+    F: FnOnce(&str) -> U,
+{
+    let Some(child) = node.first_child() else {
+        return default;
+    };
+    let Some(last_child) = node.last_child() else {
+        return default;
+    };
+    if !child.same_node(last_child) {
+        return default;
+    }
+    let NodeValue::Text(ref text) = child.data.borrow().value else {
+        return default;
+    };
+    f(text)
+}

data/ext/glfm_markdown/src/glfm.rs

@@ -1,16 +1,10 @@
-use std::io::{self, Write};
+use comrak::{parse_document, Arena, Plugins};
+use serde::Deserialize;
 
-use comrak::html::{collect_text, format_node_default, render_sourcepos, ChildRendering, Context};
-use comrak::nodes::{AstNode, ListType, NodeValue};
-use comrak::{create_formatter, html, parse_document, Arena, Plugins};
-use lazy_static::lazy_static;
-use regex::Regex;
+use crate::formatter::{CustomFormatter, RenderUserData};
 
-lazy_static! {
-    static ref PLACEHOLDER_REGEX: Regex = Regex::new(r"%(\{|%7B)(\w{1,30})(}|%7D)").unwrap();
-}
-
-#[derive(Debug)]
+#[derive(Debug, Default, Deserialize)]
+#[serde(default)]
 pub struct RenderOptions {
     pub alerts: bool,
     pub autolink: bool,
@@ -47,7 +41,7 @@ pub struct RenderOptions {
     pub tasklist: bool,
     pub tasklist_classes: bool,
     pub underline: bool,
-    pub unsafe_: bool,
+    pub r#unsafe: bool,
     pub wikilinks_title_after_pipe: bool,
     pub wikilinks_title_before_pipe: bool,
 
@@ -63,13 +57,10 @@ pub struct RenderOptions {
     /// have the format `%{PLACEHOLDER}`
     pub placeholder_detection: bool,
 
-    pub debug: bool,
-}
+    /// When the 'escaped_char_spans' render option is enabled, only emit `<span
+    /// data-escaped-char>` around the given characters.
+    pub only_escape_chars: Option<Vec<char>>,
 
-pub struct RenderUserData {
-    pub default_html: bool,
-    pub inapplicable_tasks: bool,
-    pub placeholder_detection: bool,
     pub debug: bool,
 }
 
@@ -79,6 +70,7 @@ impl From<&RenderOptions> for RenderUserData {
             default_html: options.default_html,
             inapplicable_tasks: options.inapplicable_tasks,
             placeholder_detection: options.placeholder_detection,
+            only_escape_chars: options.only_escape_chars.clone(),
             debug: options.debug,
         }
     }
@@ -123,7 +115,7 @@ impl From<&RenderOptions> for comrak::Options<'_> {
         comrak_options.render.tasklist_classes = options.tasklist_classes;
         // comrak_options.render.syntax_highlighting = options.syntax_highlighting;
 
-        comrak_options.render.unsafe_ = options.unsafe_;
+        comrak_options.render.unsafe_ = options.r#unsafe;
 
         // comrak_options.parse.default_info_string = options.default_info_string;
         comrak_options.parse.relaxed_autolinks = options.relaxed_autolinks;
@@ -134,356 +126,23 @@ impl From<&RenderOptions> for comrak::Options<'_> {
     }
 }
 
-pub fn render(text: String, options: RenderOptions) -> String {
+pub fn render(text: &str, options: &RenderOptions) -> String {
     render_with_plugins(text, options, &comrak::Plugins::default())
 }
 
-fn render_with_plugins(text: String, render_options: RenderOptions, plugins: &Plugins) -> String {
-    let user_data = RenderUserData::from(&render_options);
-    let options = comrak::Options::from(&render_options);
+fn render_with_plugins(text: &str, render_options: &RenderOptions, plugins: &Plugins) -> String {
+    let user_data = RenderUserData::from(render_options);
+    let options = comrak::Options::from(render_options);
 
     if user_data.default_html {
-        return comrak::markdown_to_html_with_plugins(&text, &options, plugins);
+        return comrak::markdown_to_html_with_plugins(text, &options, plugins);
     }
 
     let arena = Arena::new();
-    let root = parse_document(&arena, &text, &options);
+    let root = parse_document(&arena, text, &options);
 
-    let mut bw = Vec::new();
-    CustomFormatter::format_document_with_plugins(root, &options, &mut bw, plugins, user_data)
+    let mut out = String::new();
+    CustomFormatter::format_document_with_plugins(root, &options, &mut out, plugins, user_data)
         .unwrap();
-    String::from_utf8(bw).unwrap()
-}
-
-// The important thing to remember is that this overrides the default behavior of the
-// specified nodes. If we do override a node, then it's our responsibility to ensure that
-// any changes in the `comrak` code for those nodes is backported to here, such as when
-// `figcaption` support was added.
-// One idea to limit that would be having the ability to specify attributes that would
-// be inserted when a node is rendered. That would allow us to (in many cases) just
-// inject the changes we need. Such a feature would need to be added to `comrak`.
-create_formatter!(CustomFormatter<RenderUserData>, {
-    NodeValue::Text(_) => |context, node, entering| {
-        return render_text(context, node, entering);
-    },
-    NodeValue::Link(_) => |context, node, entering| {
-        return render_link(context, node, entering);
-    },
-    NodeValue::Image(_) => |context, node, entering| {
-        return render_image(context, node, entering);
-    },
-    NodeValue::List(_) => |context, node, entering| {
-        return render_list(context, node, entering);
-    },
-    NodeValue::TaskItem(_) => |context, node, entering| {
-        return render_task_item(context, node, entering);
-    },
-    NodeValue::Heading(_) => |context, node, entering| {
-        return render_heading(context, node, entering);
-    },
-});
-
-fn render_image<'a>(
-    context: &mut Context<RenderUserData>,
-    node: &'a AstNode<'a>,
-    entering: bool,
-) -> io::Result<ChildRendering> {
-    let NodeValue::Image(ref nl) = node.data.borrow().value else {
-        unreachable!()
-    };
-
-    if !(context.user.placeholder_detection && PLACEHOLDER_REGEX.is_match(nl.url.as_str())) {
-        return html::format_node_default(context, node, entering);
-    }
-
-    if entering {
-        if context.options.render.figure_with_caption {
-            context.write_all(b"<figure>")?;
-        }
-        context.write_all(b"<img")?;
-        html::render_sourcepos(context, node)?;
-        context.write_all(b" src=\"")?;
-        let url = nl.url.as_bytes();
-        if context.options.render.unsafe_ || !html::dangerous_url(url) {
-            if let Some(rewriter) = &context.options.extension.image_url_rewriter {
-                context.escape_href(rewriter.to_html(&nl.url).as_bytes())?;
-            } else {
-                context.escape_href(url)?;
-            }
-        }
-
-        context.write_all(b"\"")?;
-
-        if PLACEHOLDER_REGEX.is_match(nl.url.as_str()) {
-            context.write_all(b" data-placeholder")?;
-        }
-
-        context.write_all(b" alt=\"")?;
-
-        return Ok(ChildRendering::Plain);
-    } else {
-        if !nl.title.is_empty() {
-            context.write_all(b"\" title=\"")?;
-            context.escape(nl.title.as_bytes())?;
-        }
-        context.write_all(b"\" />")?;
-        if context.options.render.figure_with_caption {
-            if !nl.title.is_empty() {
-                context.write_all(b"<figcaption>")?;
-                context.escape(nl.title.as_bytes())?;
-                context.write_all(b"</figcaption>")?;
-            }
-            context.write_all(b"</figure>")?;
-        };
-    }
-
-    Ok(ChildRendering::HTML)
-}
-
-fn render_link<'a>(
-    context: &mut Context<RenderUserData>,
-    node: &'a AstNode<'a>,
-    entering: bool,
-) -> io::Result<ChildRendering> {
-    let NodeValue::Link(ref nl) = node.data.borrow().value else {
-        unreachable!()
-    };
-
-    if !(context.user.placeholder_detection && PLACEHOLDER_REGEX.is_match(nl.url.as_str())) {
-        return html::format_node_default(context, node, entering);
-    }
-
-    let parent_node = node.parent();
-
-    if !context.options.parse.relaxed_autolinks
-        || (parent_node.is_none()
-            || !matches!(
-                parent_node.unwrap().data.borrow().value,
-                NodeValue::Link(..)
-            ))
-    {
-        if entering {
-            context.write_all(b"<a")?;
-            html::render_sourcepos(context, node)?;
-            context.write_all(b" href=\"")?;
-            let url = nl.url.as_bytes();
-            if context.options.render.unsafe_ || !html::dangerous_url(url) {
-                if let Some(rewriter) = &context.options.extension.link_url_rewriter {
-                    context.escape_href(rewriter.to_html(&nl.url).as_bytes())?;
-                } else {
-                    context.escape_href(url)?;
-                }
-            }
-            context.write_all(b"\"")?;
-
-            if !nl.title.is_empty() {
-                context.write_all(b" title=\"")?;
-                context.escape(nl.title.as_bytes())?;
-            }
-
-            if PLACEHOLDER_REGEX.is_match(nl.url.as_str()) {
-                context.write_all(b" data-placeholder")?;
-            }
-
-            context.write_all(b">")?;
-        } else {
-            context.write_all(b"</a>")?;
-        }
-    }
-
-    Ok(ChildRendering::HTML)
-}
-
-// Overridden to use class `task-list` instead of `contains-task-list`
-// to align with GitLab class usage
-fn render_list<'a>(
-    context: &mut Context<RenderUserData>,
-    node: &'a AstNode<'a>,
-    entering: bool,
-) -> io::Result<ChildRendering> {
-    if !entering || !context.options.render.tasklist_classes {
-        return html::format_node_default(context, node, entering);
-    }
-
-    let NodeValue::List(ref nl) = node.data.borrow().value else {
-        unreachable!()
-    };
-
-    context.cr()?;
-    match nl.list_type {
-        ListType::Bullet => {
-            context.write_all(b"<ul")?;
-            if nl.is_task_list {
-                context.write_all(b" class=\"task-list\"")?;
-            }
-            html::render_sourcepos(context, node)?;
-            context.write_all(b">\n")?;
-        }
-        ListType::Ordered => {
-            context.write_all(b"<ol")?;
-            if nl.is_task_list {
-                context.write_all(b" class=\"task-list\"")?;
-            }
-            html::render_sourcepos(context, node)?;
-            if nl.start == 1 {
-                context.write_all(b">\n")?;
-            } else {
-                writeln!(context, " start=\"{}\">", nl.start)?;
-            }
-        }
-    }
-
-    Ok(ChildRendering::HTML)
-}
-
-// Overridden to detect inapplicable task list items
-fn render_task_item<'a>(
-    context: &mut Context<RenderUserData>,
-    node: &'a AstNode<'a>,
-    entering: bool,
-) -> io::Result<ChildRendering> {
-    if !context.user.inapplicable_tasks {
-        return html::format_node_default(context, node, entering);
-    }
-
-    let NodeValue::TaskItem(symbol) = node.data.borrow().value else {
-        unreachable!()
-    };
-
-    if symbol.is_none() || matches!(symbol, Some('x' | 'X')) {
-        return html::format_node_default(context, node, entering);
-    }
-
-    if entering {
-        // Handle an inapplicable task symbol.
-        if matches!(symbol, Some('~')) {
-            context.cr()?;
-            context.write_all(b"<li")?;
-            context.write_all(b" class=\"inapplicable")?;
-
-            if context.options.render.tasklist_classes {
-                context.write_all(b" task-list-item")?;
-            }
-            context.write_all(b"\"")?;
-
-            html::render_sourcepos(context, node)?;
-            context.write_all(b">")?;
-            context.write_all(b"<input type=\"checkbox\"")?;
-
-            if context.options.render.tasklist_classes {
-                context.write_all(b" class=\"task-list-item-checkbox\"")?;
-            }
-
-            context.write_all(b" data-inapplicable disabled=\"\"> ")?;
-        } else {
-            // Don't allow unsupported symbols to render a checkbox
-            context.cr()?;
-            context.write_all(b"<li")?;
-
-            if context.options.render.tasklist_classes {
-                context.write_all(b" class=\"task-list-item\"")?;
-            }
-
-            html::render_sourcepos(context, node)?;
-            context.write_all(b">")?;
-            context.write_all(b"[")?;
-            context.escape(symbol.unwrap().to_string().as_bytes())?;
-            context.write_all(b"] ")?;
-        }
-    } else {
-        context.write_all(b"</li>\n")?;
-    }
-
-    Ok(ChildRendering::HTML)
-}
-
-fn render_text<'a>(
-    context: &mut Context<RenderUserData>,
-    node: &'a AstNode<'a>,
-    entering: bool,
-) -> io::Result<ChildRendering> {
-    let NodeValue::Text(ref literal) = node.data.borrow().value else {
-        unreachable!()
-    };
-
-    if !(context.user.placeholder_detection && PLACEHOLDER_REGEX.is_match(literal)) {
-        return html::format_node_default(context, node, entering);
-    }
-
-    // Don't currently support placeholders in the text inside links or images.
-    // If the text has an underscore in it, then the parser will not combine
-    // the multiple text nodes in `comrak`'s `postprocess_text_nodes`, breaking up
-    // the placeholder into multiple text nodes.
-    // For example, `[%{a_b}](link)`.
-    let parent = node.parent().unwrap();
-    if matches!(
-        parent.data.borrow().value,
-        NodeValue::Link(_) | NodeValue::Image(_)
-    ) {
-        return html::format_node_default(context, node, entering);
-    }
-
-    if entering {
-        let mut cursor: usize = 0;
-
-        for mat in PLACEHOLDER_REGEX.find_iter(literal) {
-            if mat.start() > cursor {
-                context.escape(literal[cursor..mat.start()].as_bytes())?;
-            }
-
-            context.write_all(b"<span data-placeholder>")?;
-            context.escape(literal[mat.start()..mat.end()].as_bytes())?;
-            context.write_all(b"</span>")?;
-
-            cursor = mat.end();
-        }
-
-        if cursor < literal.len() {
-            context.escape(literal[cursor..literal.len()].as_bytes())?;
-        }
-    }
-
-    Ok(ChildRendering::HTML)
-}
-
-fn render_heading<'a>(
-    context: &mut Context<RenderUserData>,
-    node: &'a AstNode<'a>,
-    entering: bool,
-) -> io::Result<ChildRendering> {
-    let NodeValue::Heading(ref nh) = node.data.borrow().value else {
-        unreachable!()
-    };
-
-    match context.plugins.render.heading_adapter {
-        None => {
-            // Overrides the default handling in order to render the heading text
-            // inside the anchor tag to better support screen readers
-            if entering {
-                context.cr()?;
-                write!(context, "<h{}", nh.level)?;
-                render_sourcepos(context, node)?;
-                context.write_all(b">")?;
-
-                if let Some(ref prefix) = context.options.extension.header_ids {
-                    let mut text_content = Vec::with_capacity(20);
-                    collect_text(node, &mut text_content);
-
-                    let mut id = String::from_utf8(text_content).unwrap();
-                    id = context.anchorizer.anchorize(id);
-                    write!(
-                        context,
-                        r##"<a href="#{id}" class="anchor" id="{prefix}{id}">"##
-                    )?;
-                }
-            } else {
-                if context.options.extension.header_ids.is_some() {
-                    write!(context, "</a>")?;
-                }
-                writeln!(context, "</h{}>", nh.level)?;
-            }
-            Ok(ChildRendering::HTML)
-        }
-        Some(_adapter) => format_node_default(context, node, entering),
-    }
+    out
 }

data/ext/glfm_markdown/src/lib.rs

@@ -1,66 +1,37 @@
-use magnus::{define_module, function, prelude::*, Error, RHash, Symbol};
+use comrak::{escape_commonmark_inline, escape_commonmark_link_destination};
+use magnus::{define_module, function, prelude::*, Error, RHash, RString};
+use serde_magnus::deserialize;
 
+mod formatter;
 mod glfm;
 use glfm::{render, RenderOptions};
 
-/// Lookup symbol in provided `RHash`. Returns `false` if the key is not present
-/// or value cannot be converted to a boolean.
-fn get_bool_opt(arg: &str, options: RHash) -> bool {
-    options.lookup(Symbol::new(arg)).unwrap_or_default()
-}
+pub fn render_to_html_rs(text: RString, options: RHash) -> Result<String, Error> {
+    let render_options: RenderOptions = deserialize(options)?;
 
-fn get_string_opt(arg: &str, options: RHash) -> Option<String> {
-    options.lookup(Symbol::new(arg)).ok()
+    // SAFETY: `RString::as_str` returns a reference directly to Ruby memory.
+    // We do not hold onto or save the `&str`, or otherwise permit Ruby to GC or
+    // modify it while in `glfm::render`.
+    // https://docs.rs/magnus/latest/magnus/r_string/struct.RString.html#method.as_str
+    Ok(render(unsafe { text.as_str()? }, &render_options))
 }
 
-pub fn render_to_html_rs(text: String, options: RHash) -> String {
-    let render_options = RenderOptions {
-        alerts: get_bool_opt("alerts", options),
-        autolink: get_bool_opt("autolink", options),
-        // default_info_string: get_string_opt("default_info_string", options),
-        description_lists: get_bool_opt("description_lists", options),
-        escape: get_bool_opt("escape", options),
-        escaped_char_spans: get_bool_opt("escaped_char_spans", options),
-        figure_with_caption: get_bool_opt("figure_with_caption", options),
-        footnotes: get_bool_opt("footnotes", options),
-        // front_matter_delimiter: get_string_opt("front_matter_delimiter", options),
-        full_info_string: get_bool_opt("full_info_string", options),
-        gemojis: get_bool_opt("gemojis", options),
-        gfm_quirks: get_bool_opt("gfm_quirks", options),
-        github_pre_lang: get_bool_opt("github_pre_lang", options),
-        greentext: get_bool_opt("greentext", options),
-        hardbreaks: get_bool_opt("hardbreaks", options),
-        header_ids: get_string_opt("header_ids", options),
-        ignore_empty_links: get_bool_opt("ignore_empty_links", options),
-        ignore_setext: get_bool_opt("ignore_setext", options),
-        inapplicable_tasks: get_bool_opt("inapplicable_tasks", options),
-        math_code: get_bool_opt("math_code", options),
-        math_dollars: get_bool_opt("math_dollars", options),
-        multiline_block_quotes: get_bool_opt("multiline_block_quotes", options),
-        relaxed_autolinks: get_bool_opt("relaxed_autolinks", options),
-        relaxed_tasklist_character: get_bool_opt("relaxed_tasklist_character", options),
-        sourcepos: get_bool_opt("sourcepos", options),
-        smart: get_bool_opt("smart", options),
-        spoiler: get_bool_opt("spoiler", options),
-        strikethrough: get_bool_opt("strikethrough", options),
-        subscript: get_bool_opt("subscript", options),
-        superscript: get_bool_opt("superscript", options),
-        // syntax_highlighting: get_string_opt("syntax_highlighting", options),
-        table: get_bool_opt("table", options),
-        tagfilter: get_bool_opt("tagfilter", options),
-        tasklist: get_bool_opt("tasklist", options),
-        tasklist_classes: get_bool_opt("tasklist_classes", options),
-        underline: get_bool_opt("underline", options),
-        unsafe_: get_bool_opt("unsafe", options),
-        wikilinks_title_after_pipe: get_bool_opt("wikilinks_title_after_pipe", options),
-        wikilinks_title_before_pipe: get_bool_opt("wikilinks_title_before_pipe", options),
-
-        default_html: get_bool_opt("default_html", options),
-        placeholder_detection: get_bool_opt("placeholder_detection", options),
-        debug: get_bool_opt("debug", options),
-    };
+pub fn escape_commonmark_inline_rs(text: RString) -> Result<String, Error> {
+    // SAFETY: `RString::as_str` returns a reference directly to Ruby memory.
+    // We do not hold onto or save the `&str`, or otherwise permit Ruby to GC or
+    // modify it while in `glfm::escape_commonmark_inline`.
+    // https://docs.rs/magnus/latest/magnus/r_string/struct.RString.html#method.as_str
+    Ok(escape_commonmark_inline(unsafe { text.as_str()? }))
+}
 
-    render(text, render_options)
+pub fn escape_commonmark_link_destination_rs(text: RString) -> Result<String, Error> {
+    // SAFETY: `RString::as_str` returns a reference directly to Ruby memory.
+    // We do not hold onto or save the `&str`, or otherwise permit Ruby to GC or
+    // modify it while in `glfm::escape_commonmark_link_destination`.
+    // https://docs.rs/magnus/latest/magnus/r_string/struct.RString.html#method.as_str
+    Ok(escape_commonmark_link_destination(unsafe {
+        text.as_str()?
+    }))
 }
 
 #[magnus::init]
@@ -68,6 +39,14 @@ fn init() -> Result<(), Error> {
     let module = define_module("GLFMMarkdown")?;
 
     module.define_singleton_method("render_to_html_rs", function!(render_to_html_rs, 2))?;
+    module.define_singleton_method(
+        "escape_commonmark_inline_rs",
+        function!(escape_commonmark_inline_rs, 1),
+    )?;
+    module.define_singleton_method(
+        "escape_commonmark_link_destination_rs",
+        function!(escape_commonmark_link_destination_rs, 1),
+    )?;
 
     Ok(())
 }

data/ext/glfm_markdown/src/main.rs

@@ -1,10 +1,12 @@
-mod glfm;
-use glfm::{render, RenderOptions};
 use std::io::Read;
 use std::io::Write;
 
 use clap::Parser;
 
+mod glfm;
+use glfm::{render, RenderOptions};
+mod formatter;
+
 #[derive(Parser, Debug)]
 #[command(author, version, about, long_about = None)]
 struct Args {
@@ -70,7 +72,7 @@ struct Args {
     #[arg(long)]
     hardbreaks: bool,
 
-    /// Enable the 'header IDs` extension, with the given ID prefix
+    /// Enable the 'header IDs' extension, with the given ID prefix
     #[arg(long, value_name = "PREFIX")]
     header_ids: Option<String>,
 
@@ -148,7 +150,7 @@ struct Args {
 
     /// Output classes on tasklist elements so that they can be styled with CSS
     #[arg(long)]
-    tasklist_clases: bool,
+    tasklist_classes: bool,
 
     /// Enables underlines using double underscores
     #[arg(long)]
@@ -181,6 +183,11 @@ struct Args {
     #[arg(long)]
     placeholder_detection: bool,
 
+    /// When the 'escaped_char_spans' render option is enabled, only emit `<span
+    /// data-escaped-char>` around the characters in the supplied string.
+    #[arg(long)]
+    only_escape_chars: Option<String>,
+
     /// Show debug information
     #[arg(long)]
     debug: bool,
@@ -237,16 +244,17 @@ fn main() {
         tasklist: cli.tasklist,
         tasklist_classes: cli.tasklist_classes,
         underline: cli.underline,
-        unsafe_: cli.unsafe_,
+        r#unsafe: cli.unsafe_,
         wikilinks_title_after_pipe: cli.wikilinks_title_after_pipe,
         wikilinks_title_before_pipe: cli.wikilinks_title_before_pipe,
 
         default_html: cli.default_html,
         placeholder_detection: cli.placeholder_detection,
+        only_escape_chars: cli.only_escape_chars.map(|s| s.chars().collect()),
         debug: cli.debug,
     };
 
-    let result = render(source.to_string(), options);
+    let result = render(&source, &options);
 
     if let Some(output_filename) = cli.output {
         std::fs::write(output_filename, &result).unwrap();

data/lib/glfm_markdown/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module GLFMMarkdown
-  VERSION = '0.0.34'
+  VERSION = '0.0.35'
 end

data/lib/glfm_markdown.rb

@@ -34,7 +34,7 @@ module GLFMMarkdown
   class << self
     def to_html(markdown, options: {})
       raise TypeError, 'markdown must be a String' unless markdown.is_a?(String)
-      raise TypeError, 'markdown must be UTF-8 encoded' unless markdown.encoding.name == "UTF-8"
+      raise TypeError, 'markdown must be UTF-8 encoded' unless markdown.encoding == Encoding::UTF_8
       raise TypeError, 'options must be a Hash' unless options.is_a?(Hash)
 
       default_options = options[:glfm] ? GLFM_DEFAULT_OPTIONS : {}
@@ -44,5 +44,19 @@ module GLFMMarkdown
 
       render_to_html_rs(markdown, default_options.merge(options))
     end
+
+    def escape_commonmark_inline(text)
+      raise TypeError, 'text must be a String' unless text.is_a?(String)
+      raise TypeError, 'text must be UTF-8 encoded' unless text.encoding == Encoding::UTF_8
+
+      escape_commonmark_inline_rs(text)
+    end
+
+    def escape_commonmark_link_destination(url)
+      raise TypeError, 'url must be a String' unless url.is_a?(String)
+      raise TypeError, 'url must be UTF-8 encoded' unless url.encoding == Encoding::UTF_8
+
+      escape_commonmark_link_destination_rs(url)
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-glfm-markdown
 version: !ruby/object:Gem::Version
-  version: 0.0.34
+  version: 0.0.35
 platform: x86_64-darwin
 authors:
 - Brett Walker
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2025-09-24 00:00:00.000000000 Z
+date: 2025-09-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rb_sys
@@ -67,6 +67,7 @@ files:
 - ext/glfm_markdown/Cargo.lock
 - ext/glfm_markdown/Cargo.toml
 - ext/glfm_markdown/extconf.rb
+- ext/glfm_markdown/src/formatter.rs
 - ext/glfm_markdown/src/glfm.rs
 - ext/glfm_markdown/src/lib.rs
 - ext/glfm_markdown/src/main.rs