Improve word-breaking of module names and sizing of main page titles (#2190)

Author: DavidOliver

assets/css/content/general.css

@@ -74,30 +74,35 @@
 /* Headings
 Summary, Callbacks and Functions sections output h1 and h2,
 which we style as h2 and h3. */
-
 .content-inner {
+  --h1-size: 1.5rem;
+  --h2-size: 1.35rem;
+  --h3-size: 1.25rem;
+  --h4-h5-size: 1.15rem;
+  --h6-size: 1rem;
+
   & h1 {
-    font-size: 2rem;
+    font-size: var(--h1-size);
     margin-top: 1.75em;
   }
 
   & h2,
   & :is(#summary, #callbacks, #functions) > h1.section-heading {
-    font-size: 1.75rem;
+    font-size: var(--h2-size);
     margin-top: 1.5em;
     margin-bottom: 0.5em;
   }
 
   & h3,
   & :is(#summary, #callbacks, #functions) > h2.section-heading,
   & #summary :is(.summary-callbacks, .summary-functions) h2 {
-    font-size: 1.45rem;
+    font-size: var(--h3-size);
     margin-top: 1.5em;
     margin-bottom: 0.5em;
   }
 
   & :is(h4, h5, h6) {
-    font-size: 1.15rem;
+    font-size: var(--h4-h5-size);
     margin-top: 1.25em;
     margin-bottom: 0.5em;
   }
@@ -107,7 +112,14 @@ which we style as h2 and h3. */
   }
 
   & h6 {
-    font-size: 1rem;
+    font-size: var(--h6-size);
+  }
+}
+@container content (width > 600px) {
+  .content-inner {
+    --h1-size: 2rem;
+    --h2-size: 1.75rem;
+    --h3-size: 1.45rem;
   }
 }
 

assets/css/layout.css

@@ -1,3 +1,11 @@
+/* Layout container contexts */
+
+#main {
+  container: content / inline-size;
+}
+
+/* Layout styles */
+
 html,
 body {
   box-sizing: border-box;
@@ -62,7 +70,6 @@ body {
 }
 
 .content .content-inner {
-  container: content / inline-size;
   max-width: var(--content-width);
   min-height: 100%;
   margin: 0 auto;

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

@@ -1,6 +1,6 @@
 <%= head_template(config, module.title) %>
     <h1 id="content">
-      <%= module.title %> <%= H.module_type(module) %>
+      <%= H.breakable_module_title(module.title) %> <%= H.module_type(module) %>
     </h1>
 
     <%= if deprecated = module.deprecated do %>

lib/ex_doc/formatter/html/templates.ex

@@ -14,6 +14,13 @@ defmodule ExDoc.Formatter.HTML.Templates do
     Atom.to_string(t)
   end
 
+  @doc """
+  Returns the title with `<wbr>` after each fullstop, allowing word breaks in long module names.
+  """
+  def breakable_module_title(title) when is_binary(title) do
+    String.replace(title, ".", ".<wbr>")
+  end
+
   @doc """
   Returns the HTML formatted title for the module page.
   """

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

@@ -1,6 +1,6 @@
 <div class="summary-row">
   <div class="summary-signature">
-    <a href="<%=enc module_node.id %>.html" translate="no"><%=h module_node.title %></a>
+    <a href="<%=enc module_node.id %>.html" translate="no"><%= breakable_module_title(h module_node.title) %></a>
     <%= if deprecated = module_node.deprecated do %>
       <span class="deprecated" title="<%= h(deprecated) %>">deprecated</span>
     <% end %>

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

@@ -4,7 +4,7 @@
 <div id="top-content">
   <div class="heading-with-actions top-heading">
     <h1>
-      <span translate="no"><%= module.title %></span> <%= module_type(module) %>
+      <span translate="no"><%= breakable_module_title(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>

test/ex_doc/formatter/html_test.exs

@@ -117,7 +117,7 @@ defmodule ExDoc.Formatter.HTMLTest do
     assert content =~ ~r{<p>moduledoc</p>}
 
     assert content =~
-             ~r{<a href="CompiledWithDocs.Nested.html" translate="no">CompiledWithDocs.Nested</a>}
+             ~r{<a href="CompiledWithDocs.Nested.html" translate="no">CompiledWithDocs.<wbr>Nested</a>}
 
     assert content =~
              ~r{<a href="Mix.Tasks.TaskWithDocs.html" translate="no">mix task_with_docs</a>}