From dbfde2825b1ddfbe4406862a5fcbb6714a1b821e Mon Sep 17 00:00:00 2001
From: David Oliver <david@doliver.co.uk>
Date: Sat, 24 Jan 2026 00:23:55 +0100
Subject: [PATCH] Improve word-breaking of module names and sizing of main page
 titles

---
 assets/css/content/general.css                | 24 ++++++++++++++-----
 assets/css/layout.css                         |  9 ++++++-
 .../epub/templates/module_template.eex        |  2 +-
 lib/ex_doc/formatter/html/templates.ex        |  7 ++++++
 .../api_reference_entry_template.eex          |  2 +-
 .../html/templates/module_template.eex        |  2 +-
 test/ex_doc/formatter/html_test.exs           |  2 +-
 7 files changed, 37 insertions(+), 11 deletions(-)

diff --git a/assets/css/content/general.css b/assets/css/content/general.css
index 407c2de41..c269e8fe4 100644
--- a/assets/css/content/general.css
+++ b/assets/css/content/general.css
@@ -74,16 +74,21 @@
 /* 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;
   }
@@ -91,13 +96,13 @@ which we style as h2 and h3. */
   & 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;
   }
 }
 
diff --git a/assets/css/layout.css b/assets/css/layout.css
index de51b1ced..27c52e997 100644
--- a/assets/css/layout.css
+++ b/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;
diff --git a/lib/ex_doc/formatter/epub/templates/module_template.eex b/lib/ex_doc/formatter/epub/templates/module_template.eex
index efd7ee521..e75ed14c5 100644
--- a/lib/ex_doc/formatter/epub/templates/module_template.eex
+++ b/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 %>
diff --git a/lib/ex_doc/formatter/html/templates.ex b/lib/ex_doc/formatter/html/templates.ex
index 850e472b4..592f6de57 100644
--- a/lib/ex_doc/formatter/html/templates.ex
+++ b/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.
   """
diff --git a/lib/ex_doc/formatter/html/templates/api_reference_entry_template.eex b/lib/ex_doc/formatter/html/templates/api_reference_entry_template.eex
index 29869e8d8..759555a9f 100644
--- a/lib/ex_doc/formatter/html/templates/api_reference_entry_template.eex
+++ b/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 %>
diff --git a/lib/ex_doc/formatter/html/templates/module_template.eex b/lib/ex_doc/formatter/html/templates/module_template.eex
index 617dea7ca..f0442e825 100644
--- a/lib/ex_doc/formatter/html/templates/module_template.eex
+++ b/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>
diff --git a/test/ex_doc/formatter/html_test.exs b/test/ex_doc/formatter/html_test.exs
index 075eaac9d..12976da95 100644
--- a/test/ex_doc/formatter/html_test.exs
+++ b/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>}