markly 0.16.0 → 0.17.0

data/ext/markly/node.c

@@ -149,12 +149,12 @@ static void free_node_as(cmark_node *node) {
   switch (node->type) {
     case CMARK_NODE_CODE_BLOCK:
     case CMARK_NODE_FRONT_MATTER:
+    case CMARK_NODE_CODE:
     cmark_chunk_free(NODE_MEM(node), &node->as.code.info);
     cmark_chunk_free(NODE_MEM(node), &node->as.code.literal);
       break;
     case CMARK_NODE_TEXT:
     case CMARK_NODE_HTML_INLINE:
-    case CMARK_NODE_CODE:
     case CMARK_NODE_HTML_BLOCK:
     case CMARK_NODE_FOOTNOTE_REFERENCE:
     case CMARK_NODE_FOOTNOTE_DEFINITION:
@@ -378,11 +378,11 @@ const char *cmark_node_get_literal(cmark_node *node) {
   case CMARK_NODE_HTML_BLOCK:
   case CMARK_NODE_TEXT:
   case CMARK_NODE_HTML_INLINE:
-  case CMARK_NODE_CODE:
   case CMARK_NODE_FOOTNOTE_REFERENCE:
   case CMARK_NODE_FOOTNOTE_DEFINITION:
     return cmark_chunk_to_cstr(NODE_MEM(node), &node->as.literal);
 
+  case CMARK_NODE_CODE:
   case CMARK_NODE_CODE_BLOCK:
   case CMARK_NODE_FRONT_MATTER:
     return cmark_chunk_to_cstr(NODE_MEM(node), &node->as.code.literal);
@@ -403,11 +403,11 @@ int cmark_node_set_literal(cmark_node *node, const char *content) {
   case CMARK_NODE_HTML_BLOCK:
   case CMARK_NODE_TEXT:
   case CMARK_NODE_HTML_INLINE:
-  case CMARK_NODE_CODE:
   case CMARK_NODE_FOOTNOTE_REFERENCE:
     cmark_chunk_set_cstr(NODE_MEM(node), &node->as.literal, content);
     return 1;
 
+  case CMARK_NODE_CODE:
   case CMARK_NODE_CODE_BLOCK:
   case CMARK_NODE_FRONT_MATTER:
     cmark_chunk_set_cstr(NODE_MEM(node), &node->as.code.literal, content);
@@ -595,6 +595,59 @@ int cmark_node_set_item_index(cmark_node *node, int idx) {
   }
 }
 
+const char *cmark_node_get_code_info(cmark_node *node) {
+  if (node == NULL) {
+    return NULL;
+  }
+
+  if (node->type == CMARK_NODE_CODE ||
+      node->type == CMARK_NODE_CODE_BLOCK ||
+      node->type == CMARK_NODE_FRONT_MATTER) {
+    return cmark_chunk_to_cstr(NODE_MEM(node), &node->as.code.info);
+  } else {
+    return NULL;
+  }
+}
+
+static int valid_inline_code_info(const char *info) {
+  if (info == NULL || *info == '\0') {
+    return 1;
+  }
+
+  if (!cmark_is_inline_code_info_start_char(*info)) {
+    return 0;
+  }
+
+  while (*++info) {
+    if (!cmark_is_inline_code_info_char(*info)) {
+      return 0;
+    }
+  }
+
+  return 1;
+}
+
+int cmark_node_set_code_info(cmark_node *node, const char *info) {
+  if (node == NULL) {
+    return 0;
+  }
+
+  if (node->type == CMARK_NODE_CODE) {
+    if (!valid_inline_code_info(info)) {
+      return 0;
+    }
+
+    cmark_chunk_set_cstr(NODE_MEM(node), &node->as.code.info, info);
+    return 1;
+  } else if (node->type == CMARK_NODE_CODE_BLOCK ||
+             node->type == CMARK_NODE_FRONT_MATTER) {
+    cmark_chunk_set_cstr(NODE_MEM(node), &node->as.code.info, info);
+    return 1;
+  } else {
+    return 0;
+  }
+}
+
 const char *cmark_node_get_fence_info(cmark_node *node) {
   if (node == NULL) {
     return NULL;

data/ext/markly/xml.c

@@ -72,7 +72,6 @@ static int S_render_node(cmark_node *node, cmark_event_type ev_type,
       literal = true;
       break;
     case CMARK_NODE_TEXT:
-    case CMARK_NODE_CODE:
     case CMARK_NODE_HTML_BLOCK:
     case CMARK_NODE_HTML_INLINE:
       cmark_strbuf_puts(xml, " xml:space=\"preserve\">");
@@ -81,6 +80,18 @@ static int S_render_node(cmark_node *node, cmark_event_type ev_type,
       cmark_strbuf_puts(xml, cmark_node_get_type_string(node));
       literal = true;
       break;
+    case CMARK_NODE_CODE:
+      if (node->as.code.info.len > 0) {
+        cmark_strbuf_puts(xml, " info=\"");
+        escape_xml(xml, node->as.code.info.data, node->as.code.info.len);
+        cmark_strbuf_putc(xml, '"');
+      }
+      cmark_strbuf_puts(xml, " xml:space=\"preserve\">");
+      escape_xml(xml, node->as.code.literal.data, node->as.code.literal.len);
+      cmark_strbuf_puts(xml, "</");
+      cmark_strbuf_puts(xml, cmark_node_get_type_string(node));
+      literal = true;
+      break;
     case CMARK_NODE_LIST:
       switch (cmark_node_get_list_type(node)) {
       case CMARK_ORDERED_LIST:

data/lib/markly/flags.rb

@@ -20,12 +20,15 @@ module Markly
 	UNSAFE = 1 << 17
 	# Parse front matter ("---" delimited block at start of document).
 	# The raw content is available via node.string_content and the optional
-	# format hint (e.g. "yaml", "toml") via node.fence_info; interpretation
+	# format hint (e.g. "yaml", "toml") via node.code_info; interpretation
 	# is left to the caller.
 	FRONT_MATTER = 1 << 18
+	# Parse language prefixes on inline code spans, e.g. ruby:`Object.new`.
+	INLINE_CODE_INFO = 1 << 19
 	
 	PARSE_FLAGS = {
 		front_matter: FRONT_MATTER,
+		inline_code_info: INLINE_CODE_INFO,
 		validate_utf8: VALIDATE_UTF8,
 		smart_quotes: SMART,
 		liberal_html_tags: LIBERAL_HTML_TAG,

data/lib/markly/node/inspect.rb

@@ -4,20 +4,27 @@
 # Copyright, 2017, by Goro Fuji.
 # Copyright, 2017-2019, by Garen Torikian.
 # Copyright, 2020, by Olle Jonsson.
-# Copyright, 2020-2025, by Samuel Williams.
+# Copyright, 2020-2026, by Samuel Williams.
 
 require "pp"
 
 module Markly
 	class Node
+		# Provides concise pretty-printing for Markdown nodes.
 		module Inspect
+			# @constant [Integer] The indentation width used for nested node attributes.
 			PP_INDENT_SIZE = 2
 			
+			# Returns a pretty-printed representation of the node.
+			#
+			# @returns [String] The formatted node representation.
 			def inspect
 				PP.pp(self, +"", Float::INFINITY)
 			end
 			
-			# @param printer [PrettyPrint] pp
+			# Pretty-print this node and its children.
+			#
+			# @parameter printer [PrettyPrint] The pretty-print formatter.
 			def pretty_print(printer)
 				printer.group(PP_INDENT_SIZE, "#<#{self.class}(#{type}):", ">") do
 					printer.breakable
@@ -31,7 +38,7 @@ module Markly
 						list_type
 						list_start
 						list_tight
-						fence_info
+						code_info
 					].map do |name|
 						begin
 							[name, __send__(name)]

data/lib/markly/node.rb

@@ -5,17 +5,20 @@
 # Copyright, 2016-2017, by Yuki Izumi.
 # Copyright, 2017, by Goro Fuji.
 # Copyright, 2018, by Jerry van Leeuwen.
-# Copyright, 2020-2025, by Samuel Williams.
+# Copyright, 2020-2026, by Samuel Williams.
 # Copyright, 2025, by Olle Jonsson.
 
 require_relative "node/inspect"
 
 module Markly
+	# Represents a node in a parsed Markdown document tree.
 	class Node
 		include Enumerable
 		include Inspect
 		
-		# Duplicate the current node and all children.
+		# Duplicate the current node and all its children.
+		#
+		# @returns [Markly::Node] The duplicated node tree.
 		def dup
 			# This is a bit crazy, but it's the best I can come up with right now:
 			node = Markly.parse(self.to_markdown)
@@ -28,9 +31,11 @@ module Markly
 			end
 		end
 		
-		# Public: An iterator that "walks the tree," descending into children recursively.
+		# Walk the node tree recursively.
 		#
-		# block - A {Proc} representing the action to take for each child
+		# @yields {|node| ...} Each node in depth-first order, including this node.
+		# 	@parameter node [Markly::Node] The current node.
+		# @returns [Enumerator | Nil] An enumerator when no block is given.
 		def walk(&block)
 			return enum_for(:walk) unless block_given?
 			
@@ -40,39 +45,47 @@ module Markly
 			end
 		end
 		
-		# Public: Convert the node to an HTML string.
-		#
-		# flags - A {Symbol} or {Array of Symbol}s indicating the render options
-		# extensions - An {Array of Symbol}s indicating the extensions to use
+		# Convert the node to an HTML string.
 		#
-		# Returns a {String}.
+		# @parameter flags [Integer] The enabled rendering flags.
+		# @parameter extensions [Array(Symbol)] The extensions to enable.
+		# @returns [String] The rendered HTML.
 		def to_html(flags: DEFAULT, extensions: [])
 			_render_html(flags, extensions).force_encoding("utf-8")
 		end
 		
-		# Public: Convert the node to a CommonMark string.
-		#
-		# flags - A {Symbol} or {Array of Symbol}s indicating the render options
-		# width - Column to wrap the output at
+		# Convert the node to a CommonMark string.
 		#
-		# Returns a {String}.
+		# @parameter flags [Integer] The enabled rendering flags.
+		# @parameter width [Integer] The column at which to wrap output, or `0` to disable wrapping.
+		# @returns [String] The rendered CommonMark text.
 		def to_commonmark(flags: DEFAULT, width: 0)
 			_render_commonmark(flags, width).force_encoding("utf-8")
 		end
 		
 		alias to_markdown to_commonmark
 		
-		# Public: Convert the node to a plain text string.
+		# Return the language identifier from the code info string.
 		#
-		# flags - A {Symbol} or {Array of Symbol}s indicating the render options
-		# width - Column to wrap the output at
+		# @returns [String | Nil] The language identifier, or `nil` when none is present.
+		def code_language
+			code_info.split(/\s+/, 2).first
+		end
+		
+		# Convert the node to a plain-text string.
 		#
-		# Returns a {String}.
+		# @parameter flags [Integer] The enabled rendering flags.
+		# @parameter width [Integer] The column at which to wrap output, or `0` to disable wrapping.
+		# @returns [String] The rendered plain text.
 		def to_plaintext(flags: DEFAULT, width: 0)
 			_render_plaintext(flags, width).force_encoding("utf-8")
 		end
 		
-		# Public: Iterate over the children (if any) of the current pointer.
+		# Iterate over the direct children of this node.
+		#
+		# @yields {|child| ...} Each direct child of this node.
+		# 	@parameter child [Markly::Node] The current child node.
+		# @returns [Enumerator | Nil] An enumerator when no block is given.
 		def each
 			return enum_for(:each) unless block_given?
 			
@@ -84,6 +97,10 @@ module Markly
 			end
 		end
 		
+		# Finds a direct child header with the given text.
+		#
+		# @parameter title [String] The header text to match.
+		# @returns [Markly::Node | Nil] The matching header, if present.
 		def find_header(title)
 			each do |child|
 				if child.type == :header && child.first_child.string_content == title
@@ -94,7 +111,9 @@ module Markly
 		
 		# Delete all nodes until the block returns true.
 		#
-		# @returns [Markly::Node] the node that returned true.
+		# @yields {|node| ...} Each node before it is deleted.
+		# 	@parameter node [Markly::Node] The current node.
+		# @returns [Markly::Node | Nil] The node for which the block returned `true`, if any.
 		def delete_until
 			current = self
 			while current
@@ -107,9 +126,9 @@ module Markly
 		
 		# Replace a section (header + content) with a new node.
 		#
-		# @parameter new_node [Markly::Node] the node to replace the section with.
-		# @parameter replace_header [Boolean] whether to replace the header itself or not.
-		# @parameter remove_subsections [Boolean] whether to remove subsections or not.
+		# @parameter new_node [Markly::Node | Nil] The node with which to replace the section.
+		# @parameter replace_header [Boolean] Whether to replace the header itself.
+		# @parameter remove_subsections [Boolean] Whether to remove subsections.
 		def replace_section(new_node, replace_header: true, remove_subsections: true)
 			# Delete until the next heading:
 			self.next&.delete_until do |node|
@@ -120,21 +139,27 @@ module Markly
 			self.delete if replace_header
 		end
 		
-		def next_heading
+		# Finds the next sibling header.
+		#
+		# @returns [Markly::Node | Nil] The next header, if present.
+		def next_header
 			current = self.next
 			while current
-				if current.type == :heading
+				if current.type == :header
 					return current
 				end
 				current = current.next
 			end
 		end
 		
+		# An alias for {ruby Markly::Node#next_header}.
+		alias next_heading next_header
+		
 		# Append the given node after the current node.
 		#
 		# It's okay to provide a document node, its children will be appended.
 		#
-		# @parameter node [Markly::Node] the node to append.
+		# @parameter node [Markly::Node] The node to append.
 		def append_after(node)
 			if node.type == :document
 				node = node.first_child
@@ -153,7 +178,7 @@ module Markly
 		#
 		# It's okay to provide a document node, its children will be appended.
 		#
-		# @parameter node [Markly::Node] the node to append.
+		# @parameter node [Markly::Node] The node to append.
 		def append_before(node)
 			if node.type == :document
 				node = node.first_child
@@ -169,7 +194,7 @@ module Markly
 		
 		# Extract the children as a fragment.
 		#
-		# @returns [Markly::Node] the fragment.
+		# @returns [Markly::Node] The fragment.
 		def extract_children
 			fragment = Markly::Node.new(:custom_inline)
 			

data/lib/markly/renderer/generic.rb

@@ -3,26 +3,37 @@
 # Released under the MIT License.
 # Copyright, 2015-2019, by Garen Torikian.
 # Copyright, 2016-2017, by Yuki Izumi.
-# Copyright, 2020-2025, by Samuel Williams.
+# Copyright, 2020-2026, by Samuel Williams.
 
 require "set"
 require "stringio"
 
 module Markly
+	# @namespace
 	module Renderer
+		# Base class for renderers implemented in Ruby.
 		class Generic
+			# Initializes a renderer with rendering flags and extensions.
+			#
+			# @parameter flags [Integer] The enabled rendering flags.
+			# @parameter extensions [Array(Symbol)] The enabled extensions.
 			def initialize(flags: DEFAULT, extensions: [])
 				@flags = flags
 				@stream = StringIO.new(+"")
-				@need_blocksep = false
 				@in_tight = false
 				@in_plain = false
 				@tagfilter = extensions.include?(:tagfilter)
 			end
 			
+			# @attribute [Boolean] Whether the renderer is inside a tight container.
 			attr_accessor :in_tight
+			
+			# @attribute [Boolean] Whether the renderer is emitting plain text.
 			attr_accessor :in_plain
 			
+			# Writes strings, nodes, arrays of nodes, or child-node markers to the output.
+			#
+			# @parameter args [Array(Object)] Values to append or render.
 			def out(*args)
 				args.each do |arg|
 					if arg == :children
@@ -37,6 +48,10 @@ module Markly
 				end
 			end
 			
+			# Renders a node and returns the completed output for document nodes.
+			#
+			# @parameter node [Markly::Node] The node to render.
+			# @returns [String | Nil] The output string when rendering a document.
 			def render(node)
 				@node = node
 				if node.type == :document
@@ -49,42 +64,57 @@ module Markly
 				end
 			end
 			
+			# Renders a document node and all of its children.
+			#
+			# @parameter _node [Markly::Node] The document node.
 			def document(_node)
 				out(:children)
 			end
 			
-			def code_block(node)
-				code_block(node)
+			# Renders a code block node.
+			#
+			# Subclasses should override this callback.
+			# @parameter _node [Markly::Node] The code block node.
+			def code_block(_node)
+				raise NotImplementedError, "#{self.class} must implement #code_block"
 			end
 			
+			# Ignores reference-definition nodes, which have no direct output.
+			#
+			# @parameter _node [Markly::Node] The reference-definition node.
 			def reference_def(_node); end
 			
+			# Writes a newline unless the output is empty or already ends with one.
+			#
 			def cr
 				return if @stream.string.empty? || @stream.string[-1] == "\n"
 				
 				out("\n")
 			end
 			
-			def blocksep
-				out("\n")
-			end
-			
-			def containersep
-				cr unless @in_tight
-			end
-			
+			# Renders a block surrounded by normalized newlines.
+			#
+			# @yields {|| ...} The block content to render.
 			def block
 				cr
 				yield
 				cr
 			end
 			
+			# Renders content between opening and closing strings.
+			#
+			# @parameter starter [String] The opening output.
+			# @parameter ender [String] The closing output.
+			# @yields {|| ...} The container content to render.
 			def container(starter, ender)
 				out(starter)
 				yield
 				out(ender)
 			end
 			
+			# Renders a block in plain-text mode, suppressing structural markup.
+			#
+			# @yields {|| ...} The content to render as plain text.
 			def plain
 				old_in_plain = @in_plain
 				@in_plain = true

data/lib/markly/renderer/headings.rb

@@ -1,20 +1,22 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 module Markly
 	module Renderer
 		# Extracts headings from a markdown document with unique anchor IDs.
 		# Handles duplicate heading text by appending counters (e.g., "deployment", "deployment-2", "deployment-3").
 		class Headings
+			# Initializes an empty heading-anchor registry.
 			def initialize
 				@ids = {}
 			end
 			
 			# Generate a unique anchor for a node.
-			# @parameter node [Markly::Node] The heading node
-			# @returns [String] A unique anchor ID
+			#
+			# @parameter node [Markly::Node] The heading node.
+			# @returns [String] A unique anchor ID.
 			def anchor_for(node)
 				base = base_anchor_for(node)
 				
@@ -28,10 +30,11 @@ module Markly
 			end
 			
 			# Extract all headings from a document root with unique anchors.
-			# @parameter root [Markly::Node] The document root node
-			# @parameter min_level [Integer] Minimum heading level to extract (default: 1)
-			# @parameter max_level [Integer] Maximum heading level to extract (default: 6)
-			# @returns [Array<Heading>] Array of heading objects with unique anchors
+			#
+			# @parameter root [Markly::Node] The document root node.
+			# @parameter min_level [Integer] The minimum heading level to extract.
+			# @parameter max_level [Integer] The maximum heading level to extract.
+			# @returns [Array(Heading)] The extracted headings with unique anchors.
 			def extract(root, min_level: 1, max_level: 6)
 				headings = []
 				root.walk do |node|
@@ -50,11 +53,12 @@ module Markly
 				headings
 			end
 			
-			# Class method for convenience - creates a new instance and extracts headings.
-			# @parameter root [Markly::Node] The document root node
-			# @parameter min_level [Integer] Minimum heading level to extract (default: 1)
-			# @parameter max_level [Integer] Maximum heading level to extract (default: 6)
-			# @returns [Array<Heading>] Array of heading objects with unique anchors
+			# Extract all headings using a new heading-anchor registry.
+			#
+			# @parameter root [Markly::Node] The document root node.
+			# @parameter min_level [Integer] The minimum heading level to extract.
+			# @parameter max_level [Integer] The maximum heading level to extract.
+			# @returns [Array(Heading)] The extracted headings with unique anchors.
 			def self.extract(root, min_level: 1, max_level: 6)
 				new.extract(root, min_level: min_level, max_level: max_level)
 			end
@@ -62,8 +66,9 @@ module Markly
 			private
 			
 			# Generate a base anchor from a node's text content.
-			# @parameter node [Markly::Node] The heading node
-			# @returns [String] The base anchor (lowercase, hyphenated)
+			#
+			# @parameter node [Markly::Node] The heading node.
+			# @returns [String] The lowercase, hyphenated base anchor.
 			def base_anchor_for(node)
 				text = node.to_plaintext.chomp.downcase
 				text.gsub(/\s+/, "-")
@@ -71,11 +76,11 @@ module Markly
 		end
 		
 		# Represents a heading extracted from a document.
-		# @attribute node [Markly::Node] The original heading node
-		# @attribute level [Integer] The heading level (1-6)
-		# @attribute text [String] The plain text content of the heading
-		# @attribute anchor [String] The unique anchor ID for this heading
+		#
+		# The structure contains the original `node`, its `level`, its plain-text
+		# `text`, and its unique `anchor`.
+		#
+		# @constant [Class] The heading data class.
 		Heading = Struct.new(:node, :level, :text, :anchor, keyword_init: true)
 	end
 end
-