Move action links out from heading tags (#1993)

Avoids action link text being read out as part of "navigated to..."
announcements.

Closes #1987.

Author: DavidOliver

assets/css/content/functions.css

@@ -16,21 +16,16 @@
 }
 
 .content-inner .detail-header {
-  margin: 2 0 1em;
-  padding: 0.5em 1em;
+  margin: 1em 0;
+  padding: 0.5em 0.85em 0.5em 1em;
   background-color: var(--textDetailBackground);
   border-left: 3px solid var(--textDetailAccent);
   font-size: 1em;
   font-family: var(--monoFontFamily);
   position: relative;
 }
 
-.content-inner .detail-header .note {
-  float: right;
-}
-
 .content-inner .detail-header .signature {
-  display: inline-block;
   font-family: var(--monoFontFamily);
   font-size: 1rem;
   font-weight: 700;
@@ -62,6 +57,10 @@
   }
 }
 
+.content-inner .detail-header .icon-action {
+  margin-top: 3px;
+}
+
 .content-inner .specs pre {
   font-family: var(--monoFontFamily);
   font-size: 0.9em;

assets/css/content/general.css

@@ -7,6 +7,40 @@
   color: var(--textBody);
 }
 
+.content-inner .heading-with-actions {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: flex-end;
+  align-items: start;
+  gap: 6px;
+}
+.content-inner .heading-with-actions > *:not(h1) {
+  flex-shrink: 0;
+}
+.content-inner .heading-with-actions h1 {
+  flex-grow: 1;
+  justify-self: flex-start;
+  max-width: 100%;
+  margin: 0;
+  overflow-wrap: break-word;
+}
+.content-inner .heading-with-actions .icon-action {
+  width: 20px;
+  height: 20px;
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  font-weight: normal;
+}
+.content-inner .heading-with-actions.top-heading .icon-action {
+  padding-top: 1.5rem;
+  font-size: 1.2rem;
+}
+
+.content-inner .top-heading {
+  padding-top: 1rem;
+}
+
 .content-inner :is(h1, h2, h3, h4, h5, h6) {
   font-family: var(--sansFontFamily);
   font-weight: 700;
@@ -20,10 +54,6 @@
   margin: 0.5em 0;
 }
 
-.content-inner h1.signature {
-  margin: 0;
-}
-
 .content-inner h1.section-heading {
   margin: 1.5em 0 0.5em;
 }
@@ -32,11 +62,6 @@
   font-weight: 300;
 }
 
-.content-inner h1 .icon-action {
-  font-size: 1.2rem;
-  font-weight: normal;
-}
-
 .content-inner h2 {
   font-size: 1.6em;
   padding-top: 1em;
@@ -65,17 +90,13 @@
 }
 
 .content-inner .icon-action {
-  float: right;
   color: var(--iconAction);
   text-decoration: none;
   border: none;
   transition: color 0.3s ease-in-out;
   background-color: transparent;
   cursor: pointer;
 }
-.content-inner button.icon-action {
-  margin-top: 12px;
-}
 .content-inner .icon-action:hover {
   color: var(--iconActionHover);
 }

lib/ex_doc/formatter/html/templates/detail_template.eex

@@ -6,15 +6,17 @@
     <a href="#<%=enc node.id %>" class="detail-link" data-no-tooltip aria-label="Link to this <%= pretty_type(node) %>">
       <i class="ri-link-m" aria-hidden="true"></i>
     </a>
-    <h1 class="signature" translate="no"><%=h node.signature %></h1>
-    <%= if node.source_url do %>
-      <a href="<%= node.source_url %>" class="icon-action" rel="help" aria-label="View Source">
-       <i class="ri-code-s-slash-line" aria-hidden="true"></i>
-     </a>
-    <% end %>
-    <%= for annotation <- node.annotations do %>
-      <span class="note">(<%= annotation %>)</span>
-    <% end %>
+    <div class="heading-with-actions">
+      <h1 class="signature" translate="no"><%=h node.signature %></h1>
+      <%= for annotation <- node.annotations do %>
+        <span class="note">(<%= annotation %>)</span>
+      <% end %>
+      <%= if node.source_url do %>
+        <a href="<%= node.source_url %>" class="icon-action" rel="help" aria-label="View Source">
+          <i class="ri-code-s-slash-line" aria-hidden="true"></i>
+        </a>
+      <% end %>
+    </div>
   </div>
   <%= if deprecated = node.deprecated do %>
     <div class="deprecated">

lib/ex_doc/formatter/html/templates/extra_template.eex

@@ -2,22 +2,21 @@
 <%= sidebar_template(config, type, nodes_map) %>
 
 <div id="top-content">
-  <h1>
+  <div class="heading-with-actions top-heading">
+    <h1><%= node.title_content %></h1>
+    <%= if type == :cheatmd do %>
+      <button onclick="window.print()" title="Print Cheatsheet" class="icon-action" rel="print">
+        <i class="ri-printer-line" aria-hidden="true"></i>
+        <span class="sr-only">Print Cheatsheet</span>
+      </button>
+    <% end %>
     <%= if node.source_url do %>
       <a href="<%= node.source_url %>" title="View Source" class="icon-action" rel="help">
         <i class="ri-code-s-slash-line" aria-hidden="true"></i>
         <span class="sr-only">View Source</span>
       </a>
     <% end %>
-    <%= if type == :cheatmd do %>
-      <button onclick="window.print()" title="Print Cheatsheet" class="icon-action" rel="print">
-        <i class="ri-printer-line" aria-hidden="true"></i>
-        <span class="sr-only">Print cheatsheet</span>
-      </button>
-    <% end %>
-
-    <span><%= node.title_content %></span>
-  </h1>
+  </div>
 
   <%= if type == :livemd do %>
     <div class="livebook-badge-container">

lib/ex_doc/formatter/html/templates/module_template.eex

@@ -2,19 +2,21 @@
 <%= sidebar_template(config, module.type, nodes_map) %>
 
 <div id="top-content">
-  <h1>
+  <div class="heading-with-actions top-heading">
+    <h1>
+      <span translate="no"><%= module.title %></span> <%= module_type(module) %>
+      <small class="app-vsn" translate="no">(<%= config.project %> v<%= config.version %>)</small>
+      <%= for annotation <- module.annotations do %>
+        <span class="note">(<%= annotation %>)</span>
+      <% end %>
+    </h1>
     <%= if module.source_url do %>
       <a href="<%= module.source_url %>" title="View Source" class="icon-action" rel="help">
         <i class="ri-code-s-slash-line" aria-hidden="true"></i>
         <span class="sr-only">View Source</span>
       </a>
     <% end %>
-    <span translate="no"><%= module.title %></span> <%= module_type(module) %>
-    <small class="app-vsn" translate="no">(<%= config.project %> v<%= config.version %>)</small>
-    <%= for annotation <- module.annotations do %>
-      <span class="note">(<%= annotation %>)</span>
-    <% end %>
-  </h1>
+  </div>
 
   <%= if deprecated = module.deprecated do %>
     <div class="deprecated">
@@ -54,4 +56,5 @@
     </div>
   </section>
 <% end %>
+
 <%= footer_template(config, module) %>

test/ex_doc/formatter/html_test.exs

@@ -108,8 +108,8 @@ defmodule ExDoc.Formatter.HTMLTest do
     foo_content = EasyHTML.parse!(File.read!("#{c.tmp_dir}/html/readme-1.html"))["#content"]
     bar_content = EasyHTML.parse!(File.read!("#{c.tmp_dir}/html/readme-2.html"))["#content"]
 
-    assert to_string(foo_content["h1 > span"]) == "README foo"
-    assert to_string(bar_content["h1 > span"]) == "README bar"
+    assert to_string(foo_content["h1"]) == "README foo"
+    assert to_string(bar_content["h1"]) == "README bar"
   end
 
   test "warns when generating an index.html file with an invalid redirect",
@@ -499,14 +499,14 @@ defmodule ExDoc.Formatter.HTMLTest do
 
       content = File.read!(tmp_dir <> "/html/plaintextfiles.html")
 
-      assert content =~ ~r{Plain Text Files</span>.*</h1>}s
+      assert content =~ ~r{Plain Text Files</h1>}s
 
       assert content =~
                ~r{<p>Read the <a href="license.html">license</a> and the <a href="plaintext.html">plain-text file</a>.}
 
       plain_text_file = File.read!(tmp_dir <> "/html/plaintext.html")
 
-      assert plain_text_file =~ ~r{PlainText</span>.*</h1>}s
+      assert plain_text_file =~ ~r{PlainText</h1>}s
 
       assert plain_text_file =~
                ~r{<pre>\nThis is plain\n  text and nothing\n.+\s+good bye\n</pre>}s
@@ -516,14 +516,14 @@ defmodule ExDoc.Formatter.HTMLTest do
 
       license = File.read!(tmp_dir <> "/html/license.html")
 
-      assert license =~ ~r{LICENSE</span>.*</h1>}s
+      assert license =~ ~r{LICENSE</h1>}s
 
       assert license =~
                ~s{<pre>\nLicensed under the Apache License, Version 2.0 (the &quot;License&quot;)}
 
       content = File.read!(tmp_dir <> "/html/livebookfile.html")
 
-      assert content =~ ~r{<span>Title for Livebook Files</span>\s*</h1>}
+      assert content =~ ~r{Title for Livebook Files</h1>}
 
       assert content =~
                ~s{<a href="https://github.com/elixir-lang/elixir/blob/main/test/fixtures/LivebookFile.livemd#L1" title="View Source"}
@@ -635,7 +635,7 @@ defmodule ExDoc.Formatter.HTMLTest do
 
       content = File.read!(tmp_dir <> "/html/plaintextfiles.html")
 
-      assert content =~ ~r{Plain Text Files</span>.*</h1>}s
+      assert content =~ ~r{Plain Text Files</h1>}s
 
       assert content =~
                ~r{<p>Read the <a href="linked-license.html">license</a> and the <a href="plain_text.html">plain-text file</a>.}