@@ -62,19 +62,82 @@ def accept(visitor)
6262 visitor . accept_heading ( self )
6363 end
6464
65- # An HTML-safe anchor reference for this header.
65+ # An HTML-safe anchor reference for this header using GitHub-style formatting:
66+ # - Lowercase
67+ # - Spaces converted to hyphens
68+ # - Special characters removed (except hyphens)
69+ #
70+ # Examples:
71+ # "Hello" -> "hello"
72+ # "Hello World" -> "hello-world"
73+ # "Foo Bar Baz" -> "foo-bar-baz"
74+ #
6675 #: () -> String
6776 def aref
68- "label- #{ self . class . to_label . convert text . dup } "
77+ self . class . to_label . convert text . dup
6978 end
7079
71- # Creates a fully-qualified label which will include the label from +context+. This helps keep ids unique in HTML.
80+ # An HTML-safe anchor reference using legacy RDoc formatting:
81+ # - Prefixed with "label-"
82+ # - Original case preserved
83+ # - Spaces converted to + (URL encoding style)
84+ # - Special characters percent-encoded
85+ #
86+ # Returns nil if it would be the same as the GitHub-style aref (no alias needed).
87+ #
88+ # Examples:
89+ # "hello" -> "label-hello" (different due to label- prefix)
90+ # "Hello" -> "label-Hello"
91+ # "Hello World" -> "label-Hello+World"
92+ # "Foo Bar Baz" -> "label-Foo+Bar+Baz"
93+ #
94+ #: () -> String?
95+ def legacy_aref
96+ "label-#{ self . class . to_label . convert_legacy text . dup }
97+ end
98+
99+ # Creates a fully-qualified label (GitHub-style) which includes the context's aref prefix.
100+ # This helps keep IDs unique in HTML when headings appear within class/method documentation.
101+ #
102+ # Examples (without context):
103+ # "Hello World" -> "hello-world"
104+ #
105+ # Examples (with context being class Foo):
106+ # "Hello World" -> "class-foo-hello-world"
107+ #
108+ # Examples (with context being method #bar):
109+ # "Hello World" -> "method-i-bar-hello-world"
110+ #
72111 #: (RDoc::Context?) -> String
73112 def label ( context = nil )
74- label = +""
75- label << "#{ context . aref } if context &.respond_to? ( :aref )
76- label << aref
77- label
113+ result = +""
114+ result << "#{ context . aref } if context &.respond_to? ( :aref )
115+ result << aref
116+ result
117+ end
118+
119+ # Creates a fully-qualified legacy label for backward compatibility.
120+ # This is used to generate a secondary ID attribute on the heading's inner anchor,
121+ # allowing old-style links (e.g., #label-Hello+World) to continue working.
122+ #
123+ # Examples (without context):
124+ # "hello" -> "label-hello"
125+ # "Hello World" -> "label-Hello+World"
126+ #
127+ # Examples (with context being class Foo):
128+ # "hello" -> "class-Foo-label-hello"
129+ # "Hello World" -> "class-Foo-label-Hello+World"
130+ #
131+ #: (RDoc::Context?) -> String
132+ def legacy_label ( context = nil )
133+ result = +""
134+ if context &.respond_to? ( :legacy_aref )
135+ result << "#{ context . legacy_aref }
136+ elsif context &.respond_to? ( :aref )
137+ result << "#{ context . aref }
138+ end
139+ result << legacy_aref
140+ result
78141 end
79142
80143 # HTML markup of the text of this label without the surrounding header element.
0 commit comments