From d9260e447b426e2b92dbe0b17eb0f81a9c80aa8a Mon Sep 17 00:00:00 2001
From: Stan Lo <stan001212@gmail.com>
Date: Thu, 1 Jan 2026 23:00:28 +0000
Subject: [PATCH 1/2] Use GitHub-style anchors for headings and
 cross-references

Anchors Generated:

| Context | Before | After |
|---------|--------|-------|
| Heading `== Hello` (standalone) | `id="label-Hello"` | `id="hello"` |
| Heading `== Hello` (in class Foo) | `id="class-Foo-label-Hello"` | `id="class-foo-hello"` |
| Heading `== Hello` (in method #bar) | `id="method-i-bar-label-Hello"` | `id="method-i-bar-hello"` |
| Class/Module anchor | `id="class-Foo::Bar"` | `id="class-foo-bar"` |

Legacy anchors preserved as hidden `<span class="legacy-anchor">` elements.

Links Generated:

| Syntax | Before | After |
|--------|--------|-------|
| `rdoc-ref:@foo` | `href="#label-foo"` | `href="#foo"` |
| `rdoc-ref:Class@foo` | `href="#class-Class-label-foo"` | `href="#class-class-foo"` |
| `rdoc-ref:Class#method@foo` | `href="#method-i-method-label-foo"` | `href="#method-i-method-foo"` |
| `rdoc-ref:Class@Section Title` | `href="#Section Title"` | `href="#section-title"` |

These changes now enable Markdown links to work with GitHub-style anchors.

Markdown `[link](#foo)` passes through unchanged as `href="#foo"`.

- Before: Anchor was `id="label-Foo"` -> link broken
- After: Anchor is `id="foo"` -> link works

Supportive Changes:

- ToC sidebar links updated to use new anchor format
---
 lib/rdoc/code_object/class_module.rb          | 20 ++++-
 lib/rdoc/code_object/context/section.rb       | 21 ++++-
 lib/rdoc/generator/template/aliki/class.rhtml |  2 +
 .../generator/template/aliki/css/rdoc.css     | 20 +++++
 .../generator/template/darkfish/class.rhtml   |  2 +
 .../generator/template/darkfish/css/rdoc.css  | 19 +++++
 lib/rdoc/markup/heading.rb                    | 77 +++++++++++++++++--
 lib/rdoc/markup/to_html.rb                    | 27 +++++--
 lib/rdoc/markup/to_html_crossref.rb           | 29 +++++--
 lib/rdoc/markup/to_label.rb                   | 12 ++-
 lib/rdoc/parser/changelog.rb                  |  8 ++
 lib/rdoc/text.rb                              | 15 ++++
 test/rdoc/code_object/normal_class_test.rb    |  4 +-
 test/rdoc/code_object/normal_module_test.rb   |  4 +-
 test/rdoc/generator/darkfish_test.rb          | 10 ++-
 test/rdoc/generator/markup_test.rb            |  3 +-
 test/rdoc/markup/heading_test.rb              | 33 +++++++-
 test/rdoc/markup/to_html_crossref_test.rb     | 35 +++++----
 test/rdoc/markup/to_html_test.rb              | 33 +++++---
 test/rdoc/markup/to_label_test.rb             | 18 +++--
 test/rdoc/rdoc_context_section_test.rb        |  4 +-
 21 files changed, 324 insertions(+), 72 deletions(-)

diff --git a/lib/rdoc/code_object/class_module.rb b/lib/rdoc/code_object/class_module.rb
index d7ee36f950..00e406b1a6 100644
--- a/lib/rdoc/code_object/class_module.rb
+++ b/lib/rdoc/code_object/class_module.rb
@@ -188,10 +188,26 @@ def aref_prefix # :nodoc:
   end
 
   ##
-  # HTML fragment reference for this module or class.  See
-  # RDoc::NormalClass#aref and RDoc::NormalModule#aref
+  # HTML fragment reference for this module or class using GitHub-style
+  # anchor format (lowercase, :: replaced with -).
+  #
+  # Examples:
+  #   Foo      -> class-foo
+  #   Foo::Bar -> class-foo-bar
 
   def aref
+    "#{aref_prefix}-#{full_name.downcase.gsub('::', '-')}"
+  end
+
+  ##
+  # Legacy HTML fragment reference for backward compatibility.
+  # Returns the old RDoc-style anchor format.
+  #
+  # Examples:
+  #   Foo      -> class-Foo
+  #   Foo::Bar -> class-Foo::Bar
+
+  def legacy_aref
     "#{aref_prefix}-#{full_name}"
   end
 
diff --git a/lib/rdoc/code_object/context/section.rb b/lib/rdoc/code_object/context/section.rb
index 16b778174f..7600a16935 100644
--- a/lib/rdoc/code_object/context/section.rb
+++ b/lib/rdoc/code_object/context/section.rb
@@ -70,11 +70,30 @@ def add_comment(comment)
   end
 
   ##
-  # Anchor reference for linking to this section
+  # Anchor reference for linking to this section using GitHub-style format.
+  #
+  # Examples:
+  #   "Section"     -> "section"
+  #   "One Two"     -> "one-two"
+  #   "[untitled]"  -> "untitled"
 
   def aref
     title = @title || '[untitled]'
 
+    RDoc::Text.to_anchor(title)
+  end
+
+  ##
+  # Legacy anchor reference for backward compatibility.
+  #
+  # Examples:
+  #   "Section"     -> "section"
+  #   "One Two"     -> "one+two"
+  #   "[untitled]"  -> "5Buntitled-5D"
+
+  def legacy_aref
+    title = @title || '[untitled]'
+
     CGI.escape(title).gsub('%', '-').sub(/^-/, '')
   end
 
diff --git a/lib/rdoc/generator/template/aliki/class.rhtml b/lib/rdoc/generator/template/aliki/class.rhtml
index 69adfab1ad..5a6fa35b18 100644
--- a/lib/rdoc/generator/template/aliki/class.rhtml
+++ b/lib/rdoc/generator/template/aliki/class.rhtml
@@ -29,6 +29,7 @@
     </ol>
   <% end %>
 
+  <span id="<%= h klass.legacy_aref %>" class="legacy-anchor"></span>
   <h1 id="<%= h klass.aref %>" class="anchor-link <%= klass.type %>">
     <%= klass.type %> <%= klass.full_name %>
   </h1>
@@ -38,6 +39,7 @@
   </section>
 
   <%- klass.each_section do |section, constants, attributes| %>
+  <span id="<%= section.legacy_aref %>" class="legacy-anchor"></span>
   <section id="<%= section.aref %>" class="documentation-section anchor-link">
     <%- if section.title then %>
     <header class="documentation-section-title">
diff --git a/lib/rdoc/generator/template/aliki/css/rdoc.css b/lib/rdoc/generator/template/aliki/css/rdoc.css
index 7158b4326c..b99f663147 100644
--- a/lib/rdoc/generator/template/aliki/css/rdoc.css
+++ b/lib/rdoc/generator/template/aliki/css/rdoc.css
@@ -1190,6 +1190,26 @@ main .anchor-link:target {
   scroll-margin-top: calc(var(--layout-header-height) + 2rem);
 }
 
+/* Legacy anchor for backward compatibility with old label- prefix links */
+.legacy-anchor {
+  display: block;
+  position: relative;
+  visibility: hidden;
+  scroll-margin-top: calc(var(--layout-header-height) + 2rem);
+}
+
+/* When a legacy anchor is targeted, highlight the next heading sibling */
+.legacy-anchor:target + h1,
+.legacy-anchor:target + h2,
+.legacy-anchor:target + h3,
+.legacy-anchor:target + h4,
+.legacy-anchor:target + h5,
+.legacy-anchor:target + h6 {
+  margin-left: calc(-1 * var(--space-5));
+  padding-left: calc(var(--space-5) / 2);
+  border-left: calc(var(--space-5) / 2) solid var(--color-border-default);
+}
+
 
 /* Utility Classes */
 .hide { display: none !important; }
diff --git a/lib/rdoc/generator/template/darkfish/class.rhtml b/lib/rdoc/generator/template/darkfish/class.rhtml
index 94481083d5..50fbe2873f 100644
--- a/lib/rdoc/generator/template/darkfish/class.rhtml
+++ b/lib/rdoc/generator/template/darkfish/class.rhtml
@@ -33,6 +33,7 @@
     </ol>
   <% end %>
 
+  <span id="<%= h klass.legacy_aref %>" class="legacy-anchor"></span>
   <h1 id="<%= h klass.aref %>" class="anchor-link <%= klass.type %>">
     <%= klass.type %> <%= klass.full_name %>
   </h1>
@@ -42,6 +43,7 @@
   </section>
 
   <%- klass.each_section do |section, constants, attributes| %>
+  <span id="<%= section.legacy_aref %>" class="legacy-anchor"></span>
   <section id="<%= section.aref %>" class="documentation-section anchor-link">
     <%- if section.title then %>
     <header class="documentation-section-title">
diff --git a/lib/rdoc/generator/template/darkfish/css/rdoc.css b/lib/rdoc/generator/template/darkfish/css/rdoc.css
index c84a604c8c..87bf24c36e 100644
--- a/lib/rdoc/generator/template/darkfish/css/rdoc.css
+++ b/lib/rdoc/generator/template/darkfish/css/rdoc.css
@@ -92,6 +92,25 @@ main .anchor-link:target {
   scroll-margin-top: 1rem;
 }
 
+/* Legacy anchor for backward compatibility with old label- prefix links */
+.legacy-anchor {
+  display: block;
+  position: relative;
+  visibility: hidden;
+  scroll-margin-top: 1rem;
+}
+
+/* When a legacy anchor is targeted, highlight the next heading sibling */
+.legacy-anchor:target + h1,
+.legacy-anchor:target + h2,
+.legacy-anchor:target + h3,
+.legacy-anchor:target + h4,
+.legacy-anchor:target + h5,
+.legacy-anchor:target + h6 {
+  margin-left: -10px;
+  border-left: 10px solid var(--border-color);
+}
+
 /* 4. Links */
 a {
   color: var(--link-color);
diff --git a/lib/rdoc/markup/heading.rb b/lib/rdoc/markup/heading.rb
index fdbe8f1d1e..e07b00bcc0 100644
--- a/lib/rdoc/markup/heading.rb
+++ b/lib/rdoc/markup/heading.rb
@@ -62,19 +62,82 @@ def accept(visitor)
         visitor.accept_heading(self)
       end
 
-      # An HTML-safe anchor reference for this header.
+      # An HTML-safe anchor reference for this header using GitHub-style formatting:
+      # - Lowercase
+      # - Spaces converted to hyphens
+      # - Special characters removed (except hyphens)
+      #
+      # Examples:
+      #   "Hello"       -> "hello"
+      #   "Hello World" -> "hello-world"
+      #   "Foo Bar Baz" -> "foo-bar-baz"
+      #
       #: () -> String
       def aref
-        "label-#{self.class.to_label.convert text.dup}"
+        self.class.to_label.convert text.dup
       end
 
-      # Creates a fully-qualified label which will include the label from +context+. This helps keep ids unique in HTML.
+      # An HTML-safe anchor reference using legacy RDoc formatting:
+      # - Prefixed with "label-"
+      # - Original case preserved
+      # - Spaces converted to + (URL encoding style)
+      # - Special characters percent-encoded
+      #
+      # Returns nil if it would be the same as the GitHub-style aref (no alias needed).
+      #
+      # Examples:
+      #   "hello"       -> "label-hello" (different due to label- prefix)
+      #   "Hello"       -> "label-Hello"
+      #   "Hello World" -> "label-Hello+World"
+      #   "Foo Bar Baz" -> "label-Foo+Bar+Baz"
+      #
+      #: () -> String?
+      def legacy_aref
+        "label-#{self.class.to_label.convert_legacy text.dup}"
+      end
+
+      # Creates a fully-qualified label (GitHub-style) which includes the context's aref prefix.
+      # This helps keep IDs unique in HTML when headings appear within class/method documentation.
+      #
+      # Examples (without context):
+      #   "Hello World" -> "hello-world"
+      #
+      # Examples (with context being class Foo):
+      #   "Hello World" -> "class-foo-hello-world"
+      #
+      # Examples (with context being method #bar):
+      #   "Hello World" -> "method-i-bar-hello-world"
+      #
       #: (RDoc::Context?) -> String
       def label(context = nil)
-        label = +""
-        label << "#{context.aref}-" if context&.respond_to?(:aref)
-        label << aref
-        label
+        result = +""
+        result << "#{context.aref}-" if context&.respond_to?(:aref)
+        result << aref
+        result
+      end
+
+      # Creates a fully-qualified legacy label for backward compatibility.
+      # This is used to generate a secondary ID attribute on the heading's inner anchor,
+      # allowing old-style links (e.g., #label-Hello+World) to continue working.
+      #
+      # Examples (without context):
+      #   "hello"       -> "label-hello"
+      #   "Hello World" -> "label-Hello+World"
+      #
+      # Examples (with context being class Foo):
+      #   "hello"       -> "class-Foo-label-hello"
+      #   "Hello World" -> "class-Foo-label-Hello+World"
+      #
+      #: (RDoc::Context?) -> String
+      def legacy_label(context = nil)
+        result = +""
+        if context&.respond_to?(:legacy_aref)
+          result << "#{context.legacy_aref}-"
+        elsif context&.respond_to?(:aref)
+          result << "#{context.aref}-"
+        end
+        result << legacy_aref
+        result
       end
 
       # HTML markup of the text of this label without the surrounding header element.
diff --git a/lib/rdoc/markup/to_html.rb b/lib/rdoc/markup/to_html.rb
index 19274e48ff..22b2236cdd 100644
--- a/lib/rdoc/markup/to_html.rb
+++ b/lib/rdoc/markup/to_html.rb
@@ -312,6 +312,13 @@ def accept_heading(heading)
     level = [6, heading.level].min
 
     label = heading.label @code_object
+    legacy_label = heading.legacy_label @code_object
+
+    # Add legacy anchor before the heading for backward compatibility.
+    # This allows old links with label- prefix to still work.
+    if @options.output_decoration && !@options.pipe
+      @res << "\n<span id=\"#{legacy_label}\" class=\"legacy-anchor\"></span>"
+    end
 
     @res << if @options.output_decoration
               "\n<h#{level} id=\"#{label}\">"
@@ -368,14 +375,18 @@ def convert_string(text)
   end
 
   ##
-  # Generate a link to +url+ with content +text+.  Handles the special cases
-  # for img: and link: described under handle_regexp_HYPERLINK
+  # Generates an HTML link or image tag for the given +url+ and +text+.
+  #
+  # - Image URLs (http/https/link ending in .gif, .png, .jpg, .jpeg, .bmp)
+  #   become <img> tags
+  # - File references (.rb, .rdoc, .md) are converted to .html paths
+  # - Anchor URLs (#foo) pass through unchanged for GitHub-style header linking
+  # - Footnote links get wrapped in <sup> tags
 
   def gen_url(url, text)
     scheme, url, id = parse_url url
 
-    if %w[http https link].include?(scheme) and
-       url =~ /\.(gif|png|jpg|jpeg|bmp)$/ then
+    if %w[http https link].include?(scheme) && url =~ /\.(gif|png|jpg|jpeg|bmp)\z/
       "<img src=\"#{url}\" />"
     else
       if scheme != 'link' and %r%\A((?!https?:)(?:[^/#]*/)*+)([^/#]+)\.(rb|rdoc|md)(?=\z|#)%i =~ url
@@ -387,9 +398,11 @@ def gen_url(url, text)
 
       link = "<a#{id} href=\"#{url}\">#{text}</a>"
 
-      link = "<sup>#{link}</sup>" if /"foot/ =~ id
-
-      link
+      if /"foot/.match?(id)
+        "<sup>#{link}</sup>"
+      else
+        link
+      end
     end
   end
 
diff --git a/lib/rdoc/markup/to_html_crossref.rb b/lib/rdoc/markup/to_html_crossref.rb
index c05a3b5b17..ad600663bf 100644
--- a/lib/rdoc/markup/to_html_crossref.rb
+++ b/lib/rdoc/markup/to_html_crossref.rb
@@ -169,14 +169,33 @@ def link(name, text, code = true, rdoc_ref: false)
       end
 
       if label
+        # Convert label to GitHub-style anchor format
+        # First convert + to space (URL encoding), then apply GitHub-style rules
+        formatted_label = RDoc::Text.to_anchor(label.tr('+', ' '))
+
+        # Case 1: Path already has an anchor (e.g., method link)
+        #   Input:  C1#method@label -> path="C1.html#method-i-m"
+        #   Output: C1.html#method-i-m-label
         if path =~ /#/
-          path << "-label-#{label}"
-        elsif ref&.sections&.any? { |section| label == section.title }
-          path << "##{label}"
+          path << "-#{formatted_label}"
+
+        # Case 2: Label matches a section title
+        #   Input:  C1@Section -> path="C1.html", section "Section" exists
+        #   Output: C1.html#section (uses section.aref for GitHub-style)
+        elsif (section = ref&.sections&.find { |s| label.tr('+', ' ') == s.title })
+          path << "##{section.aref}"
+
+        # Case 3: Ref has an aref (class/module context)
+        #   Input:  C1@heading -> path="C1.html", ref=C1 class
+        #   Output: C1.html#class-c1-heading
         elsif ref.respond_to?(:aref)
-          path << "##{ref.aref}-label-#{label}"
+          path << "##{ref.aref}-#{formatted_label}"
+
+        # Case 4: No context, just the label (e.g., TopLevel/file)
+        #   Input:  README@section -> path="README_md.html"
+        #   Output: README_md.html#section
         else
-          path << "#label-#{label}"
+          path << "##{formatted_label}"
         end
       end
 
diff --git a/lib/rdoc/markup/to_label.rb b/lib/rdoc/markup/to_label.rb
index 9d6d5cc324..22ec07f9c1 100644
--- a/lib/rdoc/markup/to_label.rb
+++ b/lib/rdoc/markup/to_label.rb
@@ -28,11 +28,21 @@ def initialize(markup = nil)
   end
 
   ##
-  # Converts +text+ to an HTML-safe label
+  # Converts +text+ to an HTML-safe label using GitHub-style anchor formatting.
 
   def convert(text)
     label = convert_flow @am.flow text
 
+    RDoc::Text.to_anchor(label)
+  end
+
+  ##
+  # Converts +text+ to an HTML-safe label using legacy RDoc formatting.
+  # Used for generating backward-compatible anchor aliases.
+
+  def convert_legacy(text)
+    label = convert_flow @am.flow text
+
     CGI.escape(label).gsub('%', '-').sub(/^-/, '')
   end
 
diff --git a/lib/rdoc/parser/changelog.rb b/lib/rdoc/parser/changelog.rb
index b8ad2393b1..85ec46e0aa 100644
--- a/lib/rdoc/parser/changelog.rb
+++ b/lib/rdoc/parser/changelog.rb
@@ -293,6 +293,10 @@ def level
       end
 
       def aref
+        commit
+      end
+
+      def legacy_aref
         "label-#{commit}"
       end
 
@@ -300,6 +304,10 @@ def label(context = nil)
         aref
       end
 
+      def legacy_label(context = nil)
+        legacy_aref
+      end
+
       def text
         case base
         when nil
diff --git a/lib/rdoc/text.rb b/lib/rdoc/text.rb
index f3c79a1632..7f715ae861 100644
--- a/lib/rdoc/text.rb
+++ b/lib/rdoc/text.rb
@@ -319,4 +319,19 @@ def wrap(txt, line_len = 76)
 
   SPACE_SEPARATED_LETTER_CLASS = /[\p{Nd}\p{Lc}\p{Pc}]|[!-~&&\W]/
 
+  ##
+  # Converts +text+ to a GitHub-style anchor ID:
+  # - Lowercase
+  # - Remove characters that aren't alphanumeric, space, or hyphen
+  # - Replace spaces with hyphens
+  #
+  # Examples:
+  #   "Hello World"  -> "hello-world"
+  #   "Foo::Bar"     -> "foobar"
+  #   "What's New?"  -> "whats-new"
+
+  module_function def to_anchor(text)
+    text.downcase.gsub(/[^a-z0-9 \-]/, '').gsub(' ', '-')
+  end
+
 end
diff --git a/test/rdoc/code_object/normal_class_test.rb b/test/rdoc/code_object/normal_class_test.rb
index 431ca4b3f1..a097619635 100644
--- a/test/rdoc/code_object/normal_class_test.rb
+++ b/test/rdoc/code_object/normal_class_test.rb
@@ -23,8 +23,8 @@ def test_ancestors_multilevel
   end
 
   def test_aref
-    assert_equal 'class-C1',     @c1.aref
-    assert_equal 'class-C2::C3', @c2_c3.aref
+    assert_equal 'class-c1',    @c1.aref
+    assert_equal 'class-c2-c3', @c2_c3.aref
   end
 
   def test_direct_ancestors
diff --git a/test/rdoc/code_object/normal_module_test.rb b/test/rdoc/code_object/normal_module_test.rb
index 0a45b950f6..0017d450ff 100644
--- a/test/rdoc/code_object/normal_module_test.rb
+++ b/test/rdoc/code_object/normal_module_test.rb
@@ -25,8 +25,8 @@ def test_ancestors_module
   end
 
   def test_aref
-    assert_equal 'module-M1',     @m1.aref
-    assert_equal 'module-M1::M2', @m1_m2.aref
+    assert_equal 'module-m1',    @m1.aref
+    assert_equal 'module-m1-m2', @m1_m2.aref
   end
 
   def test_definition
diff --git a/test/rdoc/generator/darkfish_test.rb b/test/rdoc/generator/darkfish_test.rb
index 87ce9d9309..ddce14632e 100644
--- a/test/rdoc/generator/darkfish_test.rb
+++ b/test/rdoc/generator/darkfish_test.rb
@@ -125,11 +125,13 @@ def test_generate
       klassnav
     )
 
-    assert_match(/<h1 id="class-Klass-label-Heading\+1"><a href="#class-Klass-label-Heading\+1">Heading 1<\/a>(?!\.)/,
+    # GitHub-style: heading-1 (lowercase, dot removed)
+    # Legacy anchor preserves original casing (class-Klass), while new anchor is lowercase (class-klass)
+    assert_match(/<span id="class-Klass-label-Heading\+1" class="legacy-anchor"><\/span>\s*<h1 id="class-klass-heading-1"><a href="#class-klass-heading-1">Heading 1<\/a>(?!\.)/,
                  klass[%r[<section class=\"description\">.*</section>]m])
     toc = File.binread('table_of_contents.html')
     assert_match(
-      %r[<a\s+href="Klass\.html#class-Klass-label-Heading\+1">Heading 1</a>]m,
+      %r[<a\s+href="Klass\.html#class-klass-heading-1">Heading 1</a>]m,
       toc[%r[<h2\s+id=\"classes\">.*(?=<h2\b)]m][%r[<a\s+href="Klass\.html".*(?=</li\b)]m]
     )
   end
@@ -171,8 +173,8 @@ def test_generate_index_with_main_page
     index_html = File.binread('index.html')
 
     assert_include index_html, "<h3>Table of Contents</h3>"
-    assert_include index_html, '<h1 id="label-Heading+1"><a href="#label-Heading+1">Heading 1</a>'
-    # When there's a main page, the default description should not be shown
+    assert_include index_html, '<span id="label-Heading+1" class="legacy-anchor"></span>'
+    assert_include index_html, '<h1 id="heading-1"><a href="#heading-1">Heading 1</a>'
     assert_not_include index_html, 'This is the API documentation for My awesome Ruby project.'
   end
 
diff --git a/test/rdoc/generator/markup_test.rb b/test/rdoc/generator/markup_test.rb
index 77c2b20e50..e78f1a4265 100644
--- a/test/rdoc/generator/markup_test.rb
+++ b/test/rdoc/generator/markup_test.rb
@@ -38,7 +38,8 @@ def test_cvs_url
   def test_description
     @comment = '= Hello'
 
-    assert_equal "\n<h1 id=\"label-Hello\"><a href=\"#label-Hello\">Hello</a></h1>\n", description
+    # When there's no context (self returns nil for aref), there's no context prefix in the legacy label
+    assert_equal "\n<span id=\"label-Hello\" class=\"legacy-anchor\"></span>\n<h1 id=\"hello\"><a href=\"#hello\">Hello</a></h1>\n", description
   end
 
   def test_formatter
diff --git a/test/rdoc/markup/heading_test.rb b/test/rdoc/markup/heading_test.rb
index 0fb83a329d..6a12b85972 100644
--- a/test/rdoc/markup/heading_test.rb
+++ b/test/rdoc/markup/heading_test.rb
@@ -10,16 +10,41 @@ def setup
   end
 
   def test_aref
-    assert_equal 'label-Hello+Friend-21', @h.aref
+    assert_equal 'hello-friend', @h.aref
   end
 
   def test_label
-    assert_equal 'label-Hello+Friend-21', @h.label
-    assert_equal 'label-Hello+Friend-21', @h.label(nil)
+    assert_equal 'hello-friend', @h.label
+    assert_equal 'hello-friend', @h.label(nil)
 
     context = RDoc::NormalClass.new 'Foo'
 
-    assert_equal 'class-Foo-label-Hello+Friend-21', @h.label(context)
+    assert_equal 'class-foo-hello-friend', @h.label(context)
+  end
+
+  def test_legacy_aref
+    # Note: *Friend* markup is stripped, ! becomes %21 which becomes -21
+    assert_equal 'label-Hello+Friend-21', @h.legacy_aref
+  end
+
+  def test_legacy_label
+    assert_equal 'label-Hello+Friend-21', @h.legacy_label
+    assert_equal 'label-Hello+Friend-21', @h.legacy_label(nil)
+
+    context = RDoc::NormalClass.new 'Foo'
+    assert_equal 'class-Foo-label-Hello+Friend-21', @h.legacy_label(context)
+  end
+
+  def test_legacy_label_preserves_context_casing
+    h = RDoc::Markup::Heading.new 1, 'Credits'
+    context = RDoc::NormalModule.new 'RDoc'
+    assert_equal 'module-RDoc-label-Credits', h.legacy_label(context)
+
+    # Nested module example
+    parent = RDoc::NormalModule.new 'Foo'
+    context = RDoc::NormalClass.new 'Bar'
+    context.parent = parent
+    assert_equal 'class-Foo::Bar-label-Credits', h.legacy_label(context)
   end
 
   def test_plain_html
diff --git a/test/rdoc/markup/to_html_crossref_test.rb b/test/rdoc/markup/to_html_crossref_test.rb
index 3f5377cdba..cf61460297 100644
--- a/test/rdoc/markup/to_html_crossref_test.rb
+++ b/test/rdoc/markup/to_html_crossref_test.rb
@@ -74,26 +74,26 @@ def test_convert_CROSSREF_method
 
   def test_convert_CROSSREF_label
     result = @to.convert 'C1@foo'
-    assert_equal para("<a href=\"C1.html#class-C1-label-foo\">foo at <code>C1</code></a>"), result
+    assert_equal para("<a href=\"C1.html#class-c1-foo\">foo at <code>C1</code></a>"), result
 
     result = @to.convert 'C1#m@foo'
-    assert_equal para("<a href=\"C1.html#method-i-m-label-foo\">foo at <code>C1#m</code></a>"),
+    assert_equal para("<a href=\"C1.html#method-i-m-foo\">foo at <code>C1#m</code></a>"),
                  result
   end
 
   def test_convert_CROSSREF_label_for_md
     result = @to.convert 'EXAMPLE@foo'
-    assert_equal para("<a href=\"EXAMPLE_md.html#label-foo\">foo at <code>EXAMPLE</code></a>"), result
+    assert_equal para("<a href=\"EXAMPLE_md.html#foo\">foo at <code>EXAMPLE</code></a>"), result
   end
 
   def test_convert_CROSSREF_label_period
     result = @to.convert 'C1@foo.'
-    assert_equal para("<a href=\"C1.html#class-C1-label-foo\">foo at <code>C1</code></a>."), result
+    assert_equal para("<a href=\"C1.html#class-c1-foo\">foo at <code>C1</code></a>."), result
   end
 
   def test_convert_CROSSREF_label_space
     result = @to.convert 'C1@foo+bar'
-    assert_equal para("<a href=\"C1.html#class-C1-label-foo+bar\">foo bar at <code>C1</code></a>"),
+    assert_equal para("<a href=\"C1.html#class-c1-foo-bar\">foo bar at <code>C1</code></a>"),
                  result
   end
 
@@ -101,7 +101,14 @@ def test_convert_CROSSREF_section
     @c1.add_section 'Section'
 
     result = @to.convert 'C1@Section'
-    assert_equal para("<a href=\"C1.html#Section\">Section at <code>C1</code></a>"), result
+    assert_equal para("<a href=\"C1.html#section\">Section at <code>C1</code></a>"), result
+  end
+
+  def test_convert_CROSSREF_section_with_spaces
+    @c1.add_section 'Public Methods'
+
+    result = @to.convert 'C1@Public+Methods'
+    assert_equal para("<a href=\"C1.html#public-methods\">Public Methods at <code>C1</code></a>"), result
   end
 
   def test_convert_CROSSREF_constant
@@ -135,7 +142,7 @@ def test_convert_RDOCLINK_rdoc_ref_method
   def test_convert_RDOCLINK_rdoc_ref_method_label
     result = @to.convert 'rdoc-ref:C1#m@foo'
 
-    assert_equal para("<a href=\"C1.html#method-i-m-label-foo\">foo at <code>C1#m</code></a>"),
+    assert_equal para("<a href=\"C1.html#method-i-m-foo\">foo at <code>C1#m</code></a>"),
                  result, 'rdoc-ref:C1#m@foo'
   end
 
@@ -171,33 +178,33 @@ def test_convert_RDOCLINK_rdoc_ref_method_percent_label
 
     result = @to.convert 'rdoc-ref:C1#%@f'
 
-    assert_equal para("<a href=\"C1.html#method-i-25-label-f\">f at <code>C1#%</code></a>"),
+    assert_equal para("<a href=\"C1.html#method-i-25-f\">f at <code>C1#%</code></a>"),
                  result
 
     m.singleton = true
 
     result = @to.convert 'rdoc-ref:C1::%@f'
 
-    assert_equal para("<a href=\"C1.html#method-c-25-label-f\">f at <code>C1::%</code></a>"),
+    assert_equal para("<a href=\"C1.html#method-c-25-f\">f at <code>C1::%</code></a>"),
                  result
   end
 
   def test_convert_RDOCLINK_rdoc_ref_label
     result = @to.convert 'rdoc-ref:C1@foo'
 
-    assert_equal para("<a href=\"C1.html#class-C1-label-foo\">foo at <code>C1</code></a>"), result,
+    assert_equal para("<a href=\"C1.html#class-c1-foo\">foo at <code>C1</code></a>"), result,
                  'rdoc-ref:C1@foo'
   end
 
   def test_convert_RDOCLINK_rdoc_ref_label_in_current_file
     result = @to.convert 'rdoc-ref:@foo'
 
-    assert_equal para("<a href=\"#label-foo\">foo</a>"), result,
+    assert_equal para("<a href=\"#foo\">foo</a>"), result,
                  'rdoc-ref:@foo'
 
     result = @to.convert '{Foo}[rdoc-ref:@foo]'
 
-    assert_equal para("<a href=\"#label-foo\">Foo</a>"), result,
+    assert_equal para("<a href=\"#foo\">Foo</a>"), result,
                  '{Foo}[rdoc-ref:@foo]'
   end
 
@@ -222,7 +229,7 @@ def test_handle_regexp_CROSSREF
   end
 
   def test_handle_regexp_CROSSREF_label
-    assert_equal "<a href=\"C1.html#method-i-m-label-foo\">foo at <code>C1#m</code></a>",
+    assert_equal "<a href=\"C1.html#method-i-m-foo\">foo at <code>C1#m</code></a>",
                  REGEXP_HANDLING('C1#m@foo')
   end
 
@@ -285,7 +292,7 @@ def test_handle_regexp_TIDYLINK_rdoc
   def test_handle_regexp_TIDYLINK_label
     link = @to.handle_regexp_TIDYLINK tidy 'C1#m@foo'
 
-    assert_equal "<a href=\"C1.html#method-i-m-label-foo\">tidy</a>",
+    assert_equal "<a href=\"C1.html#method-i-m-foo\">tidy</a>",
                  link, 'C1#m@foo'
   end
 
diff --git a/test/rdoc/markup/to_html_test.rb b/test/rdoc/markup/to_html_test.rb
index 49bf51b306..3d2b010c4b 100644
--- a/test/rdoc/markup/to_html_test.rb
+++ b/test/rdoc/markup/to_html_test.rb
@@ -24,34 +24,34 @@ def accept_document
   end
 
   def accept_heading
-    assert_equal "\n<h5 id=\"label-Hello\"><a href=\"#label-Hello\">Hello</a></h5>\n", @to.res.join
+    assert_equal "\n<span id=\"label-Hello\" class=\"legacy-anchor\"></span>\n<h5 id=\"hello\"><a href=\"#hello\">Hello</a></h5>\n", @to.res.join
   end
 
   def accept_heading_1
-    assert_equal "\n<h1 id=\"label-Hello\"><a href=\"#label-Hello\">Hello</a></h1>\n", @to.res.join
+    assert_equal "\n<span id=\"label-Hello\" class=\"legacy-anchor\"></span>\n<h1 id=\"hello\"><a href=\"#hello\">Hello</a></h1>\n", @to.res.join
   end
 
   def accept_heading_2
-    assert_equal "\n<h2 id=\"label-Hello\"><a href=\"#label-Hello\">Hello</a></h2>\n", @to.res.join
+    assert_equal "\n<span id=\"label-Hello\" class=\"legacy-anchor\"></span>\n<h2 id=\"hello\"><a href=\"#hello\">Hello</a></h2>\n", @to.res.join
   end
 
   def accept_heading_3
-    assert_equal "\n<h3 id=\"label-Hello\"><a href=\"#label-Hello\">Hello</a></h3>\n", @to.res.join
+    assert_equal "\n<span id=\"label-Hello\" class=\"legacy-anchor\"></span>\n<h3 id=\"hello\"><a href=\"#hello\">Hello</a></h3>\n", @to.res.join
   end
 
   def accept_heading_4
-    assert_equal "\n<h4 id=\"label-Hello\"><a href=\"#label-Hello\">Hello</a></h4>\n", @to.res.join
+    assert_equal "\n<span id=\"label-Hello\" class=\"legacy-anchor\"></span>\n<h4 id=\"hello\"><a href=\"#hello\">Hello</a></h4>\n", @to.res.join
   end
 
   def accept_heading_b
     inner = "<strong>Hello</strong>"
 
-    assert_equal "\n<h1 id=\"label-Hello\"><a href=\"#label-Hello\">#{inner}</a></h1>\n",
+    assert_equal "\n<span id=\"label-Hello\" class=\"legacy-anchor\"></span>\n<h1 id=\"hello\"><a href=\"#hello\">#{inner}</a></h1>\n",
                  @to.res.join
   end
 
   def accept_heading_suppressed_crossref
-    assert_equal "\n<h1 id=\"label-Hello\"><a href=\"#label-Hello\">Hello</a></h1>\n", @to.res.join
+    assert_equal "\n<span id=\"label-Hello\" class=\"legacy-anchor\"></span>\n<h1 id=\"hello\"><a href=\"#hello\">Hello</a></h1>\n", @to.res.join
   end
 
   def accept_list_end_bullet
@@ -327,7 +327,7 @@ def test_accept_heading_7
 
     @to.accept_heading @RM::Heading.new(7, 'Hello')
 
-    assert_equal "\n<h6 id=\"label-Hello\"><a href=\"#label-Hello\">Hello</a></h6>\n", @to.res.join
+    assert_equal "\n<span id=\"label-Hello\" class=\"legacy-anchor\"></span>\n<h6 id=\"hello\"><a href=\"#hello\">Hello</a></h6>\n", @to.res.join
   end
 
   def test_accept_heading_aref_class
@@ -336,7 +336,7 @@ def test_accept_heading_aref_class
 
     @to.accept_heading head(1, 'Hello')
 
-    assert_equal "\n<h1 id=\"class-Foo-label-Hello\"><a href=\"#class-Foo-label-Hello\">Hello</a></h1>\n",
+    assert_equal "\n<span id=\"class-Foo-label-Hello\" class=\"legacy-anchor\"></span>\n<h1 id=\"class-foo-hello\"><a href=\"#class-foo-hello\">Hello</a></h1>\n",
                  @to.res.join
   end
 
@@ -346,7 +346,7 @@ def test_accept_heading_aref_method
 
     @to.accept_heading @RM::Heading.new(1, 'Hello')
 
-    assert_equal "\n<h1 id=\"method-i-foo-label-Hello\"><a href=\"#method-i-foo-label-Hello\">Hello</a></h1>\n",
+    assert_equal "\n<span id=\"method-i-foo-label-Hello\" class=\"legacy-anchor\"></span>\n<h1 id=\"method-i-foo-hello\"><a href=\"#method-i-foo-hello\">Hello</a></h1>\n",
                  @to.res.join
   end
 
@@ -357,7 +357,7 @@ def test_accept_heading_pipe
 
     @to.accept_heading @RM::Heading.new(1, 'Hello')
 
-    assert_equal "\n<h1 id=\"label-Hello\">Hello</h1>\n", @to.res.join
+    assert_equal "\n<h1 id=\"hello\">Hello</h1>\n", @to.res.join
   end
 
   def test_accept_paragraph_newline
@@ -407,7 +407,7 @@ def test_accept_heading_output_decoration
 
     @to.accept_heading @RM::Heading.new(1, 'Hello')
 
-    assert_equal "\n<h1><a href=\"#label-Hello\">Hello</a></h1>\n", @to.res.join
+    assert_equal "\n<h1><a href=\"#hello\">Hello</a></h1>\n", @to.res.join
   end
 
   def test_accept_heading_output_decoration_with_pipe
@@ -1040,6 +1040,15 @@ def test_accept_table
     assert_include(res[%r<<td[^<>]*>C1</td>>], 'C1')
   end
 
+  def test_gen_url_markdown_anchor
+    assert_equal '<a href="#hello-world">link</a>', @to.gen_url('#hello-world', 'link')
+  end
+
+  def test_convert_tidy_link_markdown_anchor
+    result = @to.convert('{link}[#hello]')
+    assert_equal "\n<p><a href=\"#hello\">link</a></p>\n", result
+  end
+
   def assert_escaped(unexpected, code)
     result = @to.convert(code)
     assert_not_include result, unexpected
diff --git a/test/rdoc/markup/to_label_test.rb b/test/rdoc/markup/to_label_test.rb
index cde1a66d87..53a27103f6 100644
--- a/test/rdoc/markup/to_label_test.rb
+++ b/test/rdoc/markup/to_label_test.rb
@@ -77,14 +77,15 @@ def test_convert_bold
   end
 
   def test_convert_crossref
-    assert_equal 'SomeClass', @to.convert('SomeClass')
-    assert_equal 'SomeClass', @to.convert('\\SomeClass')
+    # GitHub-style: lowercase, remove non-alphanumeric except space/hyphen
+    assert_equal 'someclass', @to.convert('SomeClass')
+    assert_equal 'someclass', @to.convert('\\SomeClass')
 
-    assert_equal 'some_method', @to.convert('some_method')
-    assert_equal 'some_method', @to.convert('\\some_method')
+    assert_equal 'somemethod', @to.convert('some_method')
+    assert_equal 'somemethod', @to.convert('\\some_method')
 
-    assert_equal '23some_method', @to.convert('#some_method')
-    assert_equal '23some_method', @to.convert('\\#some_method')
+    assert_equal 'somemethod', @to.convert('#some_method')
+    assert_equal 'somemethod', @to.convert('\\#some_method')
   end
 
   def test_convert_em
@@ -93,11 +94,12 @@ def test_convert_em
   end
 
   def test_convert_em_dash # for HTML conversion
-    assert_equal '-', @to.convert('--')
+    assert_equal '--', @to.convert('--')
   end
 
   def test_convert_escape
-    assert_equal 'a+-3E+b', @to.convert('a > b')
+    # GitHub-style: spaces become hyphens, special chars removed
+    assert_equal 'a--b', @to.convert('a > b')
   end
 
   def test_convert_tidylink
diff --git a/test/rdoc/rdoc_context_section_test.rb b/test/rdoc/rdoc_context_section_test.rb
index 179ea95014..c3db144f73 100644
--- a/test/rdoc/rdoc_context_section_test.rb
+++ b/test/rdoc/rdoc_context_section_test.rb
@@ -43,9 +43,9 @@ def test_add_comment
   def test_aref
     assert_equal 'section', @s.aref
 
-    assert_equal '5Buntitled-5D', @S.new(nil, nil, nil).aref
+    assert_equal 'untitled', @S.new(nil, nil, nil).aref
 
-    assert_equal 'one+two', @S.new(nil, 'one two', nil).aref
+    assert_equal 'one-two', @S.new(nil, 'one two', nil).aref
   end
 
   def test_eql_eh

From 00bcfa664c8111d2404a99f6951323469ba881e2 Mon Sep 17 00:00:00 2001
From: Stan Lo <stan001212@gmail.com>
Date: Sat, 3 Jan 2026 13:10:31 +0000
Subject: [PATCH 2/2] Update documentation

---
 ExampleMarkdown.md           | 13 ++++++++++++-
 ExampleRDoc.rdoc             | 12 ++++++++++++
 doc/rdoc/markup_reference.rb | 24 ++++++++++++++++--------
 3 files changed, 40 insertions(+), 9 deletions(-)

diff --git a/ExampleMarkdown.md b/ExampleMarkdown.md
index fd4359f355..8622fcab77 100644
--- a/ExampleMarkdown.md
+++ b/ExampleMarkdown.md
@@ -14,6 +14,18 @@ For the following styles, see ExampleRDoc.rdoc for style examples:
 
 These items all use the same styles as RDoc format files.
 
+## Anchor Links
+
+RDoc supports GitHub-style anchor links. You can link to any heading using its
+anchor, which is the heading text converted to lowercase with spaces replaced
+by hyphens and special characters removed.
+
+For example:
+
+* [Link to Footnotes](#footnotes)
+* [Link to Blockquotes](#blockquotes)
+* [Link to Anchor Links](#anchor-links)
+
 ## Footnotes
 
 Footnotes are rendered at the bottom of the documentation section[^1].  For
@@ -36,4 +48,3 @@ Here is how a blockquote looks.
 > > 75 years?
 
 This text is from [Riker Ipsum](http://rikeripsum.com)
-
diff --git a/ExampleRDoc.rdoc b/ExampleRDoc.rdoc
index b5dd68c19c..750fdc4795 100644
--- a/ExampleRDoc.rdoc
+++ b/ExampleRDoc.rdoc
@@ -3,6 +3,18 @@
 This document contains example output to show RDoc styling.  This file was
 created from a RDoc Markup file.
 
+== Anchor Links
+
+RDoc generates GitHub-style anchors for headings.  The anchor is the heading
+text converted to lowercase with spaces replaced by hyphens and special
+characters removed.
+
+You can link to headings using Markdown-style syntax:
+
+- {Link to Headings}[#headings]
+- {Link to Paragraphs}[#paragraphs]
+- {Link to Verbatim sections}[#verbatim-sections]
+
 == Headings
 
 You should not use headings beyond level 3, it is a sign of poor organization
diff --git a/doc/rdoc/markup_reference.rb b/doc/rdoc/markup_reference.rb
index 1ceda2656d..1729144f4c 100644
--- a/doc/rdoc/markup_reference.rb
+++ b/doc/rdoc/markup_reference.rb
@@ -957,22 +957,30 @@
 #
 # [Heading]
 #
-#   - Link: <tt>RDoc::RD@LICENSE</tt> links to RDoc::RDoc::RD@LICENSE.
+#   Headings generate GitHub-style anchors: lowercase, spaces as hyphens,
+#   special characters removed. For example, <tt>== Hello World</tt> generates
+#   anchor <tt>hello-world</tt>.
 #
-#   Note that spaces in the actual heading are represented by <tt>+</tt> characters
-#   in the linkable text.
+#   Link to headings are recommended to use the GitHub-style anchor format:
 #
-#   - Link: <tt>RDoc::Options@Saved+Options</tt>
-#     links to RDoc::Options@Saved+Options.
+#   - <tt>RDoc::Options@saved-options</tt> links to RDoc::Options@saved-options.
+#   - <tt>RDoc::RD@license</tt> links to RDoc::RD@license.
 #
-#   Punctuation and other special characters must be escaped like CGI.escape.
+#   To link to headings on the same page, you can also use Markdown-style anchor links:
+#
+#   - <tt>{link text}[#hello-world]</tt> links to the heading <tt>== Hello World</tt>.
+#   - <tt>{link text}[#saved-options]</tt> links to the heading <tt>== Saved Options</tt>.
+#
+#   The legacy format with <tt>+</tt> for spaces is also supported, but not recommended:
+#
+#   - <tt>RDoc::Options@Saved+Options</tt> links to RDoc::Options@Saved+Options.
 #
 #   Pro tip: The link to any heading is available in the alphabetical table of contents
-#   at the top left of the page for the class or module.
+#   at the right sidebar of the page.
 #
 # [Section]
 #
-#   See {Directives for Organizing Documentation}[#class-RDoc::MarkupReference-label-Directives+for+Organizing+Documentation].
+#   See {Directives for Organizing Documentation}[#class-rdoc-markupreference-directives-for-organizing-documentation].
 #
 #   - Link: <tt>RDoc::Markup::ToHtml@Visitor</tt> links to RDoc::Markup::ToHtml@Visitor.
 #