Make headers/method names directly linkable instead of using pilcrow items

Author: st0012

lib/rdoc/generator/template/aliki/class.rhtml

@@ -41,7 +41,7 @@
     <%- if section.title then %>
     <header class="documentation-section-title">
       <h2>
-        <%= section.title %>
+        <a href="#<%= section.aref %>"><%= section.title %></a>
       </h2>
     </header>
     <%- end %>
@@ -55,7 +55,7 @@
     <%- unless constants.empty? then %>
     <section class="constants-list">
       <header>
-        <h3 id="constants">Constants</h3>
+        <h3 id="constants"><a href="#constants">Constants</a></h3>
       </header>
       <dl>
       <%- constants.each do |const| %>
@@ -80,7 +80,7 @@
     <%- unless attributes.empty? then %>
     <section class="attribute-method-details method-section">
       <header>
-        <h3 id="attributes">Attributes</h3>
+        <h3 id="attributes"><a href="#attributes">Attributes</a></h3>
       </header>
 
       <%- attributes.each do |attrib| %>
@@ -115,7 +115,7 @@
          next if methods.empty? %>
      <section id="<%= visibility %>-<%= type %>-<%= section.aref %>-method-details" class="method-section anchor-link">
        <header>
-         <h3 id="<%= visibility %>-<%= type %>-methods"><%= visibility.to_s.capitalize %> <%= type.capitalize %> Methods</h3>
+         <h3 id="<%= visibility %>-<%= type %>-methods"><a href="#<%= visibility %>-<%= type %>-methods"><%= visibility.to_s.capitalize %> <%= type.capitalize %> Methods</a></h3>
        </header>
 
     <%- methods.each do |method| %>

lib/rdoc/generator/template/aliki/css/rdoc.css

@@ -225,35 +225,6 @@ body.has-toc {
 }
 
 /* 3. Typography */
-h1 span,
-h2 span,
-h3 span,
-h4 span,
-h5 span,
-h6 span {
-  position: relative;
-  display: none;
-  padding-left: 1em;
-  line-height: 0;
-  vertical-align: baseline;
-  font-size: 10px;
-}
-
-h1 span { top: -1.3em; }
-h2 span { top: -1.2em; }
-h3 span { top: -1.0em; }
-h4 span { top: -0.8em; }
-h5 span { top: -0.5em; }
-h6 span { top: -0.5em; }
-
-h1:hover span,
-h2:hover span,
-h3:hover span,
-h4:hover span,
-h5:hover span,
-h6:hover span {
-  display: inline;
-}
 
 /* 4. Links */
 a {
@@ -797,6 +768,26 @@ main h5, main h6 {
   margin-bottom: var(--space-2);
 }
 
+/* Heading links */
+main h1 a,
+main h2 a,
+main h3 a,
+main h4 a,
+main h5 a,
+main h6 a {
+  color: inherit;
+  text-decoration: none;
+}
+
+main h1 a:hover,
+main h2 a:hover,
+main h3 a:hover,
+main h4 a:hover,
+main h5 a:hover,
+main h6 a:hover {
+  text-decoration: underline;
+}
+
 /* Syntax Highlighting - Light Theme */
 .ruby-constant   { color: var(--code-orange); }
 .ruby-keyword    { color: var(--code-red); }
@@ -1012,18 +1003,6 @@ main .method-heading .method-args {
   font-weight: var(--font-weight-normal);
 }
 
-main .method-heading::after {
-  content: '¶';
-  position: absolute;
-  visibility: hidden;
-  color: var(--color-accent-primary);
-  font-size: 0.5em;
-}
-
-main .method-heading:hover::after {
-  visibility: visible;
-}
-
 main .method-controls {
   line-height: 20px;
   float: right;

lib/rdoc/generator/template/aliki/js/aliki.js

@@ -191,7 +191,7 @@ function generateToc() {
     const link = document.createElement('a');
     link.href = `#${heading.id}`;
     link.className = 'toc-link';
-    link.textContent = heading.textContent.replace(/¶.*$/, '').trim(); // Remove pilcrow link
+    link.textContent = heading.textContent.trim();
     link.setAttribute('data-target', heading.id);
 
     li.appendChild(link);

lib/rdoc/markup/to_html.rb

@@ -312,10 +312,13 @@ def accept_heading(heading)
             else
               "\n<h#{level}>"
             end
-    @res << to_html(heading.text)
-    unless @options.pipe then
-      @res << "<span><a href=\"##{label}\">&para;</a></span>"
+
+    if @options.pipe
+      @res << to_html(heading.text)
+    else
+      @res << "<a href=\"##{label}\">#{to_html(heading.text)}</a>"
     end
+
     @res << "</h#{level}>\n"
   end
 

test/rdoc/generator/darkfish_test.rb

@@ -125,7 +125,7 @@ def test_generate
       klassnav
     )
 
-    assert_match(/<h1 id="class-Klass-label-Heading\+1">Heading 1(?!\.)/,
+    assert_match(/<h1 id="class-Klass-label-Heading\+1"><a href="#class-Klass-label-Heading\+1">Heading 1<\/a>(?!\.)/,
                  klass[%r[<section class=\"description\">.*</section>]m])
     toc = File.binread('table_of_contents.html')
     assert_match(
@@ -171,7 +171,7 @@ 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">Heading 1'
+    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_not_include index_html, 'This is the API documentation for My awesome Ruby project.'
   end

test/rdoc/generator/markup_test.rb

@@ -38,9 +38,7 @@ def test_cvs_url
   def test_description
     @comment = '= Hello'
 
-    links = '<span><a href="#label-Hello">&para;</a></span>'
-
-    assert_equal "\n<h1 id=\"label-Hello\">Hello#{links}</h1>\n", description
+    assert_equal "\n<h1 id=\"label-Hello\"><a href=\"#label-Hello\">Hello</a></h1>\n", description
   end
 
   def test_formatter

test/rdoc/markup/to_html_test.rb

@@ -24,48 +24,34 @@ def accept_document
   end
 
   def accept_heading
-    links = '<span><a href="#label-Hello">&para;</a></span>'
-    expected = "\n<h5 id=\"label-Hello\">Hello#{links}</h5>\n"
-
-    assert_equal expected, @to.res.join
+    assert_equal "\n<h5 id=\"label-Hello\"><a href=\"#label-Hello\">Hello</a></h5>\n", @to.res.join
   end
 
   def accept_heading_1
-    links = '<span><a href="#label-Hello">&para;</a></span>'
-
-    assert_equal "\n<h1 id=\"label-Hello\">Hello#{links}</h1>\n", @to.res.join
+    assert_equal "\n<h1 id=\"label-Hello\"><a href=\"#label-Hello\">Hello</a></h1>\n", @to.res.join
   end
 
   def accept_heading_2
-    links = '<span><a href="#label-Hello">&para;</a></span>'
-
-    assert_equal "\n<h2 id=\"label-Hello\">Hello#{links}</h2>\n", @to.res.join
+    assert_equal "\n<h2 id=\"label-Hello\"><a href=\"#label-Hello\">Hello</a></h2>\n", @to.res.join
   end
 
   def accept_heading_3
-    links = '<span><a href="#label-Hello">&para;</a></span>'
-
-    assert_equal "\n<h3 id=\"label-Hello\">Hello#{links}</h3>\n", @to.res.join
+    assert_equal "\n<h3 id=\"label-Hello\"><a href=\"#label-Hello\">Hello</a></h3>\n", @to.res.join
   end
 
   def accept_heading_4
-    links = '<span><a href="#label-Hello">&para;</a></span>'
-
-    assert_equal "\n<h4 id=\"label-Hello\">Hello#{links}</h4>\n", @to.res.join
+    assert_equal "\n<h4 id=\"label-Hello\"><a href=\"#label-Hello\">Hello</a></h4>\n", @to.res.join
   end
 
   def accept_heading_b
-    links = '<span><a href="#label-Hello">&para;</a></span>'
     inner = "<strong>Hello</strong>"
 
-    assert_equal "\n<h1 id=\"label-Hello\">#{inner}#{links}</h1>\n",
+    assert_equal "\n<h1 id=\"label-Hello\"><a href=\"#label-Hello\">#{inner}</a></h1>\n",
                  @to.res.join
   end
 
   def accept_heading_suppressed_crossref
-    links = '<span><a href="#label-Hello">&para;</a></span>'
-
-    assert_equal "\n<h1 id=\"label-Hello\">Hello#{links}</h1>\n", @to.res.join
+    assert_equal "\n<h1 id=\"label-Hello\"><a href=\"#label-Hello\">Hello</a></h1>\n", @to.res.join
   end
 
   def accept_list_end_bullet
@@ -341,9 +327,7 @@ def test_accept_heading_7
 
     @to.accept_heading @RM::Heading.new(7, 'Hello')
 
-    links = '<span><a href="#label-Hello">&para;</a></span>'
-
-    assert_equal "\n<h6 id=\"label-Hello\">Hello#{links}</h6>\n", @to.res.join
+    assert_equal "\n<h6 id=\"label-Hello\"><a href=\"#label-Hello\">Hello</a></h6>\n", @to.res.join
   end
 
   def test_accept_heading_aref_class
@@ -352,9 +336,7 @@ def test_accept_heading_aref_class
 
     @to.accept_heading head(1, 'Hello')
 
-    links = '<span><a href="#class-Foo-label-Hello">&para;</a></span>'
-
-    assert_equal "\n<h1 id=\"class-Foo-label-Hello\">Hello#{links}</h1>\n",
+    assert_equal "\n<h1 id=\"class-Foo-label-Hello\"><a href=\"#class-Foo-label-Hello\">Hello</a></h1>\n",
                  @to.res.join
   end
 
@@ -364,9 +346,7 @@ def test_accept_heading_aref_method
 
     @to.accept_heading @RM::Heading.new(1, 'Hello')
 
-    links = '<span><a href="#method-i-foo-label-Hello">&para;</a></span>'
-
-    assert_equal "\n<h1 id=\"method-i-foo-label-Hello\">Hello#{links}</h1>\n",
+    assert_equal "\n<h1 id=\"method-i-foo-label-Hello\"><a href=\"#method-i-foo-label-Hello\">Hello</a></h1>\n",
                  @to.res.join
   end
 
@@ -427,7 +407,7 @@ def test_accept_heading_output_decoration
 
     @to.accept_heading @RM::Heading.new(1, 'Hello')
 
-    assert_equal "\n<h1>Hello<span><a href=\"#label-Hello\">&para;</a></span></h1>\n", @to.res.join
+    assert_equal "\n<h1><a href=\"#label-Hello\">Hello</a></h1>\n", @to.res.join
   end
 
   def test_accept_heading_output_decoration_with_pipe