Skip to content

[Aliki] Improve header links #1465

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Nov 22, 2025
Merged

[Aliki] Improve header links #1465

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
633e589
Remove outdated go-to-top link feature
st0012 Nov 22, 2025
f183f9b
Make headers/method names directly linkable instead of using pilcrow …
st0012 Nov 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 5 additions & 8 deletions lib/rdoc/generator/template/aliki/class.rhtml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
<body id="top" role="document" class="<%= klass.type %> has-toc">
<body role="document" class="<%= klass.type %> has-toc">
<%= render '_header.rhtml' %>
<%= render '_sidebar_toggle.rhtml' %>

Expand Down Expand Up @@ -41,11 +41,8 @@
<%- if section.title then %>
<header class="documentation-section-title">
<h2>
<%= section.title %>
<a href="#<%= section.aref %>"><%= section.title %></a>
</h2>
<span class="section-click-top">
<a href="#top">&uarr; top</a>
</span>
</header>
<%- end %>

Expand All @@ -58,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| %>
Expand All @@ -83,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| %>
Expand Down Expand Up @@ -118,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| %>
Expand Down
61 changes: 20 additions & 41 deletions lib/rdoc/generator/template/aliki/css/rdoc.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down Expand Up @@ -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); }
Expand Down Expand Up @@ -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;
Expand Down
2 changes: 1 addition & 1 deletion lib/rdoc/generator/template/aliki/index.rhtml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
<body id="top" role="document" class="file has-toc">
<body role="document" class="file has-toc">
<%= render '_header.rhtml' %>
<%= render '_sidebar_toggle.rhtml' %>

Expand Down
2 changes: 1 addition & 1 deletion lib/rdoc/generator/template/aliki/js/aliki.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 and "top" links
link.textContent = heading.textContent.trim();
link.setAttribute('data-target', heading.id);

li.appendChild(link);
Expand Down
2 changes: 1 addition & 1 deletion lib/rdoc/generator/template/aliki/page.rhtml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
<body id="top" role="document" class="file has-toc">
<body role="document" class="file has-toc">
<%= render '_header.rhtml' %>
<%= render '_sidebar_toggle.rhtml' %>

Expand Down
10 changes: 6 additions & 4 deletions lib/rdoc/markup/to_html.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -312,11 +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>"
@res << " <a href=\"#top\">&uarr;</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

Expand Down
4 changes: 2 additions & 2 deletions test/rdoc/generator/darkfish_test.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand Down Expand Up @@ -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
Expand Down
5 changes: 1 addition & 4 deletions test/rdoc/generator/markup_test.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,10 +38,7 @@ def test_cvs_url
def test_description
@comment = '= Hello'

links = '<span><a href="#label-Hello">&para;</a> ' +
'<a href="#top">&uarr;</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
Expand Down
52 changes: 11 additions & 41 deletions test/rdoc/markup/to_html_test.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,55 +24,34 @@ def accept_document
end

def accept_heading
links = '<span><a href="#label-Hello">&para;</a> ' +
'<a href="#top">&uarr;</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> ' +
'<a href="#top">&uarr;</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> ' +
'<a href="#top">&uarr;</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> ' +
'<a href="#top">&uarr;</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> ' +
'<a href="#top">&uarr;</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> ' +
'<a href="#top">&uarr;</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> ' +
'<a href="#top">&uarr;</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
Expand Down Expand Up @@ -348,10 +327,7 @@ def test_accept_heading_7

@to.accept_heading @RM::Heading.new(7, 'Hello')

links = '<span><a href="#label-Hello">&para;</a> ' +
'<a href="#top">&uarr;</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
Expand All @@ -360,10 +336,7 @@ def test_accept_heading_aref_class

@to.accept_heading head(1, 'Hello')

links = '<span><a href="#class-Foo-label-Hello">&para;</a> ' +
'<a href="#top">&uarr;</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

Expand All @@ -373,10 +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> ' +
'<a href="#top">&uarr;</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

Expand Down Expand Up @@ -437,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> <a href=\"#top\">&uarr;</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
Expand Down