markly 0.16.0 → 0.17.0

data/lib/markly/renderer/html.rb

@@ -13,14 +13,17 @@ require_relative "headings"
 
 require "cgi/escape"
 
-# Compatibility for older Ruby versions where escape_html alias doesn't exist:
-unless CGI.respond_to?(:escape_html)
-	require "cgi"
-end
-
 module Markly
 	module Renderer
+		# Renders Markdown node trees as HTML.
 		class HTML < Generic
+			# Initializes an HTML renderer.
+			#
+			# @parameter ids [Boolean] Whether to wrap headings in anchored sections.
+			# @parameter headings [Markly::Renderer::Headings | Nil] A heading tracker to reuse.
+			# @parameter tight [Boolean] Whether to render paragraphs tightly.
+			# @option :flags [Integer] The enabled rendering flags.
+			# @option :extensions [Array(Symbol)] The enabled extensions.
 			def initialize(ids: false, headings: nil, tight: false, **options)
 				super(**options)
 				
@@ -33,6 +36,9 @@ module Markly
 				@footnotes = {}
 			end
 			
+			# Renders a complete document and closes any generated sections.
+			#
+			# @parameter _ [Markly::Node] The document node.
 			def document(_)
 				@section = false
 				super
@@ -40,13 +46,22 @@ module Markly
 				out("</section>") if @section
 			end
 			
+			# Returns an escaped HTML id attribute for a heading node.
+			#
+			# @parameter node [Markly::Node] The heading node.
+			# @returns [String | Nil] The id attribute when heading IDs are enabled.
 			def id_for(node)
 				if @headings
 					anchor = @headings.anchor_for(node)
-					return " id=\"#{CGI.escape_html anchor}\""
+					# `CGI.escape_html` is not exposed by `cgi/escape` on Ruby 3.4:
+					return " id=\"#{CGI.escapeHTML anchor}\""
 				end
 			end
 			
+			# Generates a normalized anchor from a node's plain-text content.
+			#
+			# @parameter node [Markly::Node] The node to convert.
+			# @returns [String] The normalized anchor.
 			def self.anchor_for(node)
 				# Convert to plaintext, strip trailing whitespace, convert to lowercase:
 				text = node.to_plaintext.chomp.downcase
@@ -57,10 +72,17 @@ module Markly
 				return text
 			end
 			
+			# Generates a normalized anchor from a node's plain-text content.
+			#
+			# @parameter node [Markly::Node] The node to convert.
+			# @returns [String] The normalized anchor.
 			def anchor_for(node)
 				self.class.anchor_for(node)
 			end
 			
+			# Renders a heading node, optionally wrapped in an anchored section.
+			#
+			# @parameter node [Markly::Node] The heading node.
 			def header(node)
 				block do
 					if @headings
@@ -73,6 +95,9 @@ module Markly
 				end
 			end
 			
+			# Renders a paragraph node.
+			#
+			# @parameter node [Markly::Node] The paragraph node.
 			def paragraph(node)
 				if @tight && node.parent.type != :blockquote
 					out(:children)
@@ -89,6 +114,9 @@ module Markly
 				end
 			end
 			
+			# Renders an ordered or unordered list node.
+			#
+			# @parameter node [Markly::Node] The list node.
 			def list(node)
 				old_tight = @tight
 				@tight = node.list_tight
@@ -113,6 +141,9 @@ module Markly
 				@tight = old_tight
 			end
 			
+			# Renders a list-item node, including task-list attributes when present.
+			#
+			# @parameter node [Markly::Node] The list-item node.
 			def list_item(node)
 				block do
 					tasklist_data = tasklist(node)
@@ -122,6 +153,10 @@ module Markly
 				end
 			end
 			
+			# Returns the HTML fragment required for a task-list item.
+			#
+			# @parameter node [Markly::Node] The list-item node.
+			# @returns [String] The task-list fragment, or an empty string.
 			def tasklist(node)
 				return "" unless tasklist?(node)
 				
@@ -133,6 +168,9 @@ module Markly
 				"><input type=\"checkbox\" #{state} /"
 			end
 			
+			# Renders a blockquote node.
+			#
+			# @parameter node [Markly::Node] The blockquote node.
 			def blockquote(node)
 				block do
 					container("<blockquote#{source_position(node)}>\n", "</blockquote>") do
@@ -141,22 +179,30 @@ module Markly
 				end
 			end
 			
+			# Renders a thematic-break node.
+			#
+			# @parameter node [Markly::Node] The thematic-break node.
 			def hrule(node)
 				block do
 					out("<hr#{source_position(node)} />")
 				end
 			end
 			
+			# Renders a code block and its optional language metadata.
+			#
+			# @parameter node [Markly::Node] The code block node.
 			def code_block(node)
 				block do
+					language = node.code_language
+					
 					if flag_enabled?(GITHUB_PRE_LANG)
 						out("<pre#{source_position(node)}")
-						out(' lang="', node.fence_info.split(/\s+/)[0], '"') if node.fence_info && !node.fence_info.empty?
+						out(' lang="', language, '"') if language
 						out("><code>")
 					else
 						out("<pre#{source_position(node)}><code")
-						if node.fence_info && !node.fence_info.empty?
-							out(' class="language-', node.fence_info.split(/\s+/)[0], '">')
+						if language
+							out(' class="language-', language, '">')
 						else
 							out(">")
 						end
@@ -166,6 +212,9 @@ module Markly
 				end
 			end
 			
+			# Renders or omits a raw block-level HTML node according to the flags.
+			#
+			# @parameter node [Markly::Node] The raw HTML node.
 			def html(node)
 				block do
 					if flag_enabled?(UNSAFE)
@@ -176,6 +225,9 @@ module Markly
 				end
 			end
 			
+			# Renders or omits a raw inline HTML node according to the flags.
+			#
+			# @parameter node [Markly::Node] The raw inline HTML node.
 			def inline_html(node)
 				if flag_enabled?(UNSAFE)
 					out(tagfilter(node.string_content))
@@ -184,10 +236,16 @@ module Markly
 				end
 			end
 			
+			# Renders an emphasized inline node.
+			#
+			# @parameter node [Markly::Node] The emphasized node.
 			def emph(node)
 				out("<em>", :children, "</em>")
 			end
 			
+			# Renders a strongly emphasized inline node.
+			#
+			# @parameter node [Markly::Node] The strong node.
 			def strong(node)
 				if node.parent.nil? || node.parent.type == node.type
 					out(:children)
@@ -196,12 +254,18 @@ module Markly
 				end
 			end
 			
+			# Renders a link node with escaped destination and title attributes.
+			#
+			# @parameter node [Markly::Node] The link node.
 			def link(node)
 				out('<a href="', node.url.nil? ? "" : escape_href(node.url), '"')
 				out(' title="', escape_html(node.title), '"') if node.title && !node.title.empty?
 				out(">", :children, "</a>")
 			end
 			
+			# Renders an image node with plain-text alternative content.
+			#
+			# @parameter node [Markly::Node] The image node.
 			def image(node)
 				out('<img src="', escape_href(node.url), '"')
 				plain do
@@ -211,20 +275,35 @@ module Markly
 				out(" />")
 			end
 			
+			# Renders an escaped text node.
+			#
+			# @parameter node [Markly::Node] The text node.
 			def text(node)
 				out(escape_html(node.string_content))
 			end
 			
+			# Renders an inline code node and its optional language metadata.
+			#
+			# @parameter node [Markly::Node] The inline code node.
 			def code(node)
-				out("<code>")
+				language = node.code_language
+				out("<code")
+				out(' class="language-', language, '"') if language
+				out(">")
 				out(escape_html(node.string_content))
 				out("</code>")
 			end
 			
+			# Renders a hard line break.
+			#
+			# @parameter _node [Markly::Node] The line-break node.
 			def linebreak(_node)
 				out("<br />\n")
 			end
 			
+			# Renders a soft line break according to the configured flags.
+			#
+			# @parameter _ [Markly::Node] The soft-break node.
 			def softbreak(_)
 				if flag_enabled?(HARD_BREAKS)
 					out("<br />\n")
@@ -235,6 +314,9 @@ module Markly
 				end
 			end
 			
+			# Renders a table node and initializes its column alignments.
+			#
+			# @parameter node [Markly::Node] The table node.
 			def table(node)
 				@alignments = node.table_alignments
 				@needs_close_tbody = false
@@ -243,6 +325,9 @@ module Markly
 				out("</table>\n")
 			end
 			
+			# Renders a table-header row.
+			#
+			# @parameter node [Markly::Node] The table-header node.
 			def table_header(node)
 				@column_index = 0
 				
@@ -251,6 +336,9 @@ module Markly
 				@in_header = false
 			end
 			
+			# Renders a table row, opening the table body when necessary.
+			#
+			# @parameter node [Markly::Node] The table-row node.
 			def table_row(node)
 				@column_index = 0
 				if !@in_header && !@needs_close_tbody
@@ -260,22 +348,32 @@ module Markly
 				out("<tr#{source_position(node)}>\n", :children, "</tr>\n")
 			end
 			
+			# @constant [Hash(Symbol, String)] HTML attributes for table-cell alignments.
 			TABLE_CELL_ALIGNMENT = {
 				left: ' align="left"',
 				right: ' align="right"',
 				center: ' align="center"'
 			}.freeze
 			
+			# Renders a table cell using the current column alignment.
+			#
+			# @parameter node [Markly::Node] The table-cell node.
 			def table_cell(node)
 				align = TABLE_CELL_ALIGNMENT.fetch(@alignments[@column_index], "")
 				out(@in_header ? "<th#{align}#{source_position(node)}>" : "<td#{align}#{source_position(node)}>", :children, @in_header ? "</th>\n" : "</td>\n")
 				@column_index += 1
 			end
 			
+			# Renders a strikethrough node.
+			#
+			# @parameter _ [Markly::Node] The strikethrough node.
 			def strikethrough(_)
 				out("<del>", :children, "</del>")
 			end
 			
+			# Renders a footnote reference linking to its definition.
+			#
+			# @parameter node [Markly::Node] The footnote-reference node.
 			def footnote_reference(node)
 				label = node.parent_footnote_def.string_content
 				
@@ -283,6 +381,9 @@ module Markly
 				# out(node.to_html)
 			end
 			
+			# Renders a footnote definition and records its backlink target.
+			#
+			# @parameter node [Markly::Node] The footnote-definition node.
 			def footnote_definition(node)
 				unless @footnote_ix
 					out("<section class=\"footnotes\" data-footnotes>\n<ol>\n")

data/lib/markly/version.rb

@@ -6,6 +6,8 @@
 # Copyright, 2017-2018, by Ashe Connor.
 # Copyright, 2020-2026, by Samuel Williams.
 
+# @namespace
 module Markly
-	VERSION = "0.16.0"
+	# @constant [String] The version of the Markly gem.
+	VERSION = "0.17.0"
 end

data/lib/markly.rb

@@ -6,7 +6,7 @@
 # Copyright, 2015-2019, by Garen Torikian.
 # Copyright, 2015, by Nick Wellnhofer.
 # Copyright, 2016-2017, by Yuki Izumi.
-# Copyright, 2020-2025, by Samuel Williams.
+# Copyright, 2020-2026, by Samuel Williams.
 
 require "markly/markly"
 
@@ -16,14 +16,14 @@ require_relative "markly/renderer/html"
 
 require_relative "markly/version"
 
+# Parses and renders CommonMark-compatible Markdown documents.
 module Markly
-	# Public: Parses a Markdown string into a `document` node.
+	# Parse a Markdown string into a document node.
 	#
-	# string - {String} to be parsed
-	# option - A {Symbol} or {Array of Symbol}s indicating the parse options
-	# extensions - An {Array of Symbol}s indicating the extensions to use
-	#
-	# Returns the `parser` node.
+	# @parameter text [String] The Markdown text to parse.
+	# @parameter flags [Integer] The enabled parsing flags.
+	# @parameter extensions [Array(Symbol) | Nil] The extensions to enable.
+	# @returns [Markly::Node] The parsed document node.
 	def self.parse(text, flags: DEFAULT, extensions: nil)
 		parser = Parser.new(flags)
 		
@@ -34,13 +34,14 @@ module Markly
 		return parser.parse(text.encode(Encoding::UTF_8))
 	end
 	
-	# Public:  Parses a Markdown string into an HTML string.
-	#
-	# text - A {String} of text
-	# option - Either a {Symbol} or {Array of Symbol}s indicating the render options
-	# extensions - An {Array of Symbol}s indicating the extensions to use
+	# Parse a Markdown string and render it as HTML.
 	#
-	# Returns a {String} of converted HTML.
+	# @parameter text [String] The Markdown text to render.
+	# @parameter flags [Integer] The default parsing and rendering flags.
+	# @parameter parse_flags [Integer] The enabled parsing flags.
+	# @parameter render_flags [Integer] The enabled rendering flags.
+	# @parameter extensions [Array(Symbol)] The extensions to enable.
+	# @returns [String] The rendered HTML.
 	def self.render_html(text, flags: DEFAULT, parse_flags: flags, render_flags: flags, extensions: [])
 		root = self.parse(text, flags: parse_flags, extensions: extensions)
 		

data/readme.md

@@ -24,9 +24,19 @@ Please see the [project documentation](https://socketry.github.io/markly/) for m
 
 Please see the [project releases](https://socketry.github.io/markly/releases/index) for all releases.
 
+### v0.17.0
+
+  - Add opt-in language prefixes for inline code spans with `Markly::INLINE_CODE_INFO`, expose code metadata through `Node#code_info`, and provide `Node#code_language` as a convenient language accessor.
+  - Expose fenced code-block metadata through `Node#fence` and `Node::Fence`.
+  - Add `Node#next_header`, retain `Node#next_heading` as an alias, and correctly recognize header nodes.
+  - Raise `NotImplementedError` from the base renderer's unimplemented code-block callback instead of recursing indefinitely.
+  - Remove unused legacy separator helpers from the Ruby renderer.
+
 ### v0.16.0
 
-  - Update `cmark-gfm` from upstream, including a denial-of-service fix for tables with a large number of autocompleted cells, corrected `end_line` source positions for single-line and multi-line HTML blocks, and a fix for trailing newlines when rendering inline nodes.
+  - Update `cmark-gfm` from upstream, including two table-rendering protections: avoid repeatedly scanning preceding cells, and limit the number of automatically completed cells to prevent denial of service.
+  - Correct `end_line` source positions for single-line and multi-line HTML blocks.
+  - Fix trailing newlines when rendering inline nodes.
   - Add support for front matter (`CMARK_OPT_FRONT_MATTER`): a `---` delimited block at the start of a document is captured as a `CMARK_NODE_FRONT_MATTER` node.  The raw content is available via `node.string_content` and an optional format hint (e.g. `"yaml"`, `"toml"`) via `node.fence_info`.
   - Allow `:` in HTML tag names to support XML namespace prefixes (e.g. `<svg:circle>`, `<xhtml:div>`).
 

data/releases.md

@@ -1,8 +1,18 @@
 # Releases
 
+## v0.17.0
+
+  - Add opt-in language prefixes for inline code spans with `Markly::INLINE_CODE_INFO`, expose code metadata through `Node#code_info`, and provide `Node#code_language` as a convenient language accessor.
+  - Expose fenced code-block metadata through `Node#fence` and `Node::Fence`.
+  - Add `Node#next_header`, retain `Node#next_heading` as an alias, and correctly recognize header nodes.
+  - Raise `NotImplementedError` from the base renderer's unimplemented code-block callback instead of recursing indefinitely.
+  - Remove unused legacy separator helpers from the Ruby renderer.
+
 ## v0.16.0
 
-  - Update `cmark-gfm` from upstream, including a denial-of-service fix for tables with a large number of autocompleted cells, corrected `end_line` source positions for single-line and multi-line HTML blocks, and a fix for trailing newlines when rendering inline nodes.
+  - Update `cmark-gfm` from upstream, including two table-rendering protections: avoid repeatedly scanning preceding cells, and limit the number of automatically completed cells to prevent denial of service.
+  - Correct `end_line` source positions for single-line and multi-line HTML blocks.
+  - Fix trailing newlines when rendering inline nodes.
   - Add support for front matter (`CMARK_OPT_FRONT_MATTER`): a `---` delimited block at the start of a document is captured as a `CMARK_NODE_FRONT_MATTER` node.  The raw content is available via `node.string_content` and an optional format hint (e.g. `"yaml"`, `"toml"`) via `node.fence_info`.
   - Allow `:` in HTML tag names to support XML namespace prefixes (e.g. `<svg:circle>`, `<xhtml:div>`).
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: markly
 version: !ruby/object:Gem::Version
-  version: 0.16.0
+  version: 0.17.0
 platform: ruby
 authors:
 - Garen Torikian
@@ -173,7 +173,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.10
 specification_version: 4
 summary: CommonMark parser and renderer. Written in C, wrapped in Ruby.
 test_files: []