markly 0.14.1 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7eb58c81c8fca95217e5a1469baf3034785126d6ff42e9929a7d074e358b9508
-  data.tar.gz: f28760fe0280ce1ab132d7ec639584284dde3ba8077e68f2cd3617715d1211cb
+  metadata.gz: d9b96430051a815282d6f83d487fc0c0cdc636b174a1f1f775f0574950e8bab3
+  data.tar.gz: d16b1c808df1030e6bcc9c67c99f88a0eeae8d8e604b68745e0d8f4c16ac171d
 SHA512:
-  metadata.gz: ded6fff6a6355a8e78b2daa19a1581d982a35ddbcbddc38efe25d1866e9ce6136ea6eea62c1638874ff9953546a176df11e6ce462c9131ab38648185dec50a7a
-  data.tar.gz: ccc6eb379235978b3a512dee8553a425ca456b01e9f60b10d16927ae1862cda069152fcc62a02a1a60d46b274a1c8aa760183a636c528b8cdc7fdf43a367abd8
+  metadata.gz: 9e7e24631dbd95cb90ee889919be9bb6a267c6e2cf31e7355dd21f5e0c903a83a288178bffcf4430eed4ed58b3d2c014e8e3617629a9c703f063069a03cfeaf7
+  data.tar.gz: 2c51b26c4ce3d2467079ce968f0d2bae307090b49b59b0acfb7396ad00c140e276f76d9291ac4bc65e24e368005b6929990521de4749fecd678f1b6b0ed6d77d

data/lib/markly/node.rb

@@ -29,7 +29,7 @@ module Markly
 		
 		# Public: An iterator that "walks the tree," descending into children recursively.
 		#
-		# blk - A {Proc} representing the action to take for each child
+		# block - A {Proc} representing the action to take for each child
 		def walk(&block)
 			return enum_for(:walk) unless block_given?
 			
@@ -41,7 +41,7 @@ module Markly
 		
 		# Public: Convert the node to an HTML string.
 		#
-		# options - A {Symbol} or {Array of Symbol}s indicating the render options
+		# flags - A {Symbol} or {Array of Symbol}s indicating the render options
 		# extensions - An {Array of Symbol}s indicating the extensions to use
 		#
 		# Returns a {String}.
@@ -51,7 +51,7 @@ module Markly
 		
 		# Public: Convert the node to a CommonMark string.
 		#
-		# options - A {Symbol} or {Array of Symbol}s indicating the render options
+		# flags - A {Symbol} or {Array of Symbol}s indicating the render options
 		# width - Column to wrap the output at
 		#
 		# Returns a {String}.
@@ -63,7 +63,7 @@ module Markly
 		
 		# Public: Convert the node to a plain text string.
 		#
-		# options - A {Symbol} or {Array of Symbol}s indicating the render options
+		# flags - A {Symbol} or {Array of Symbol}s indicating the render options
 		# width - Column to wrap the output at
 		#
 		# Returns a {String}.
@@ -106,7 +106,6 @@ module Markly
 		
 		# Replace a section (header + content) with a new node.
 		#
-		# @parameter title [String] the title of the section to replace.
 		# @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.
@@ -132,7 +131,7 @@ module Markly
 		
 		# Append the given node after the current node.
 		#
-		# It's okay to provide a document node, it's children will be appended.
+		# It's okay to provide a document node, its children will be appended.
 		#
 		# @parameter node [Markly::Node] the node to append.
 		def append_after(node)
@@ -151,7 +150,7 @@ module Markly
 		
 		# Append the given node before the current node.
 		#
-		# It's okay to provide a document node, it's children will be appended.
+		# It's okay to provide a document node, its children will be appended.
 		#
 		# @parameter node [Markly::Node] the node to append.
 		def append_before(node)

data/lib/markly/renderer/headings.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, 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
+			def initialize
+				@ids = {}
+			end
+			
+			# Generate a unique anchor for a node.
+			# @parameter node [Markly::Node] The heading node
+			# @returns [String] A unique anchor ID
+			def anchor_for(node)
+				base = base_anchor_for(node)
+				
+				if @ids.key?(base)
+					@ids[base] += 1
+					"#{base}-#{@ids[base]}"
+				else
+					@ids[base] = 1
+					base
+				end
+			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
+			def extract(root, min_level: 1, max_level: 6)
+				headings = []
+				root.walk do |node|
+					if node.type == :header
+						level = node.header_level
+						next if level < min_level || level > max_level
+						
+						headings << Heading.new(
+							node: node,
+							level: level,
+							text: node.to_plaintext.chomp,
+							anchor: anchor_for(node)
+						)
+					end
+				end
+				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
+			def self.extract(root, min_level: 1, max_level: 6)
+				new.extract(root, min_level: min_level, max_level: max_level)
+			end
+			
+			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)
+			def base_anchor_for(node)
+				text = node.to_plaintext.chomp.downcase
+				text.gsub(/\s+/, "-")
+			end
+		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
+		Heading = Struct.new(:node, :level, :text, :anchor, keyword_init: true)
+	end
+end
+

data/lib/markly/renderer/html.rb

@@ -9,15 +9,18 @@
 # Copyright, 2020-2025, by Samuel Williams.
 
 require_relative "generic"
+require_relative "headings"
 require "cgi"
 
 module Markly
 	module Renderer
 		class HTML < Generic
-			def initialize(ids: false, tight: false, **options)
+			def initialize(ids: false, headings: nil, tight: false, **options)
 				super(**options)
 				
-				@ids = ids
+				# Initialize heading tracker if IDs are enabled
+				@headings = headings || (ids ? Headings.new : nil)
+				
 				@section = nil
 				@tight = tight
 				
@@ -32,8 +35,8 @@ module Markly
 			end
 			
 			def id_for(node)
-				if @ids
-					anchor = self.class.anchor_for(node)
+				if @headings
+					anchor = @headings.anchor_for(node)
 					return " id=\"#{CGI.escape_html anchor}\""
 				end
 			end
@@ -54,7 +57,7 @@ module Markly
 			
 			def header(node)
 				block do
-					if @ids
+					if @headings
 						out("</section>") if @section
 						@section = true
 						out("<section#{id_for(node)}>")
@@ -253,10 +256,10 @@ module Markly
 			end
 			
 			TABLE_CELL_ALIGNMENT = {
-				left: ' align="left"',
-				right: ' align="right"',
-				center: ' align="center"'
-			}.freeze
+						left: ' align="left"',
+						right: ' align="right"',
+						center: ' align="center"'
+					}.freeze
 			
 			def table_cell(node)
 				align = TABLE_CELL_ALIGNMENT.fetch(@alignments[@column_index], "")

data/lib/markly/version.rb

@@ -7,5 +7,5 @@
 # Copyright, 2020-2025, by Samuel Williams.
 
 module Markly
-	VERSION = "0.14.1"
+	VERSION = "0.15.0"
 end

data/readme.md

@@ -22,10 +22,16 @@ Please see the [project documentation](https://ioquatix.github.io/markly/) for m
 
   - [Abstract Syntax Tree](https://ioquatix.github.io/markly/guides/abstract-syntax-tree/index) - This guide explains how to use Markly's abstract syntax tree (AST) to parse and manipulate Markdown documents.
 
+  - [Headings](https://ioquatix.github.io/markly/guides/headings/index) - This guide explains how to work with headings in Markly, including extracting them for navigation and handling duplicate heading text.
+
 ## Releases
 
 Please see the [project releases](https://ioquatix.github.io/markly/releases/index) for all releases.
 
+### v0.15.0
+
+  - Introduced `Markly::Renderer::Headings` class for extracting headings from markdown documents with automatic duplicate ID resolution. When rendering HTML with `ids: true`, duplicate heading text now automatically gets unique IDs (`deployment`, `deployment-2`, `deployment-3`). The `Headings` class can also be used to extract headings for building navigation or table of contents.
+
 ### v0.14.0
 
   - Expose `Markly::Renderer::HTML.anchor_for` method to generate URL-safe anchors from headers.

data/releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## v0.15.0
+
+  - Introduced `Markly::Renderer::Headings` class for extracting headings from markdown documents with automatic duplicate ID resolution. When rendering HTML with `ids: true`, duplicate heading text now automatically gets unique IDs (`deployment`, `deployment-2`, `deployment-3`). The `Headings` class can also be used to extract headings for building navigation or table of contents.
+
 ## v0.14.0
 
   - Expose `Markly::Renderer::HTML.anchor_for` method to generate URL-safe anchors from headers.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: markly
 version: !ruby/object:Gem::Version
-  version: 0.14.1
+  version: 0.15.0
 platform: ruby
 authors:
 - Garen Torikian
@@ -138,6 +138,7 @@ files:
 - lib/markly/node.rb
 - lib/markly/node/inspect.rb
 - lib/markly/renderer/generic.rb
+- lib/markly/renderer/headings.rb
 - lib/markly/renderer/html.rb
 - lib/markly/version.rb
 - license.md