From a53f3651ecc170cd79b9b66801c17af072d777d2 Mon Sep 17 00:00:00 2001
From: David Oliver <david@doliver.co.uk>
Date: Mon, 26 Jan 2026 17:39:09 +0100
Subject: [PATCH 1/4] Fix Summary Types heading size

---
 assets/css/content/general.css | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/assets/css/content/general.css b/assets/css/content/general.css
index c269e8fe4..8146de950 100644
--- a/assets/css/content/general.css
+++ b/assets/css/content/general.css
@@ -87,15 +87,15 @@ which we style as h2 and h3. */
   }
 
   & h2,
-  & :is(#summary, #callbacks, #functions) > h1.section-heading {
+  & :is(#summary, #types, #callbacks, #functions) > h1.section-heading {
     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 {
+  & :is(#summary, #types, #callbacks, #functions) > h2.section-heading,
+  & #summary :is(.summary-types, .summary-callbacks, .summary-functions) h2 {
     font-size: var(--h3-size);
     margin-top: 1.5em;
     margin-bottom: 0.5em;

From cb47aa91f9ed2df496cac31aad0a2dabf68faa48 Mon Sep 17 00:00:00 2001
From: David Oliver <david@doliver.co.uk>
Date: Mon, 26 Jan 2026 21:13:34 +0100
Subject: [PATCH 2/4] Change headings' levels to match their context

---
 assets/css/content/general.css                           | 7 ++-----
 assets/css/content/summary.css                           | 3 ++-
 lib/ex_doc/formatter/epub/templates/module_template.eex  | 4 ++--
 lib/ex_doc/formatter/html/templates/module_template.eex  | 8 ++++----
 lib/ex_doc/formatter/html/templates/summary_template.eex | 4 ++--
 test/ex_doc/formatter/epub/templates_test.exs            | 2 +-
 6 files changed, 13 insertions(+), 15 deletions(-)

diff --git a/assets/css/content/general.css b/assets/css/content/general.css
index 8146de950..9d2d36b34 100644
--- a/assets/css/content/general.css
+++ b/assets/css/content/general.css
@@ -86,16 +86,13 @@ which we style as h2 and h3. */
     margin-top: 1.75em;
   }
 
-  & h2,
-  & :is(#summary, #types, #callbacks, #functions) > h1.section-heading {
+  & h2 {
     font-size: var(--h2-size);
     margin-top: 1.5em;
     margin-bottom: 0.5em;
   }
 
-  & h3,
-  & :is(#summary, #types, #callbacks, #functions) > h2.section-heading,
-  & #summary :is(.summary-types, .summary-callbacks, .summary-functions) h2 {
+  & h3 {
     font-size: var(--h3-size);
     margin-top: 1.5em;
     margin-bottom: 0.5em;
diff --git a/assets/css/content/summary.css b/assets/css/content/summary.css
index 2d6c6c7b1..e59f2d73e 100644
--- a/assets/css/content/summary.css
+++ b/assets/css/content/summary.css
@@ -1,4 +1,5 @@
-.content-inner .summary h2 a {
+/* Summary section subheading (e.g., Types) */
+.content-inner .summary h3 a {
   text-decoration: none;
   border: none;
   color: var(--textHeaders) !important;
diff --git a/lib/ex_doc/formatter/epub/templates/module_template.eex b/lib/ex_doc/formatter/epub/templates/module_template.eex
index e75ed14c5..cf8b1cc75 100644
--- a/lib/ex_doc/formatter/epub/templates/module_template.eex
+++ b/lib/ex_doc/formatter/epub/templates/module_template.eex
@@ -17,14 +17,14 @@
 
     <%= if module.docs_groups != [] do %>
       <section id="summary" class="details-list">
-        <h1 class="section-heading">Summary</h1>
+        <h2 class="section-heading">Summary</h2>
         <%= for group <- module.docs_groups, do: H.summary_template(group.title, group.docs) %>
       </section>
     <% end %>
 
     <%= for group <- module.docs_groups, key = text_to_id(group.title) do %>
       <section id="<%= key %>" class="details-list">
-        <h1 class="section-heading"><%=h to_string(group.title) %></h1>
+        <h2 class="section-heading"><%=h to_string(group.title) %></h2>
         <%= if doc = group.doc do %>
           <div class="group-description" id="group-description-<%= key %>">
             <%= render_doc(doc) %>
diff --git a/lib/ex_doc/formatter/html/templates/module_template.eex b/lib/ex_doc/formatter/html/templates/module_template.eex
index f0442e825..ab890bfec 100644
--- a/lib/ex_doc/formatter/html/templates/module_template.eex
+++ b/lib/ex_doc/formatter/html/templates/module_template.eex
@@ -36,24 +36,24 @@
 
 <%= if module.docs_groups != [] do %>
   <section id="summary" class="details-list">
-    <h1 class="section-heading">
+    <h2 class="section-heading">
       <a class="hover-link" href="#summary">
         <i class="ri-link-m" aria-hidden="true"></i>
       </a>
       <span class="text">Summary</span>
-    </h1>
+    </h2>
     <%= for group <- module.docs_groups, do: summary_template(group.title, group.docs) %>
   </section>
 <% end %>
 
 <%= for group <- module.docs_groups, key = text_to_id(group.title) do %>
   <section id="<%= key %>" class="details-list">
-    <h1 class="section-heading">
+    <h2 class="section-heading">
       <a class="hover-link" href="#<%= key %>">
         <i class="ri-link-m" aria-hidden="true"></i>
       </a>
       <span class="text"><%= group.title %></span>
-    </h1>
+    </h2>
     <%= if doc = group.doc do %>
       <div class="group-description" id="group-description-<%= key %>">
        <%= render_doc(doc) %>
diff --git a/lib/ex_doc/formatter/html/templates/summary_template.eex b/lib/ex_doc/formatter/html/templates/summary_template.eex
index 935148796..500518317 100644
--- a/lib/ex_doc/formatter/html/templates/summary_template.eex
+++ b/lib/ex_doc/formatter/html/templates/summary_template.eex
@@ -1,7 +1,7 @@
 <div class="summary-<%= text_to_id(name) %> summary">
-  <h2>
+  <h3>
     <a href="#<%=h text_to_id(name) %>"><%= name %></a>
-  </h2>
+  </h3>
   <%= for node <- nodes do %>
     <div class="summary-row">
       <div class="summary-signature">
diff --git a/test/ex_doc/formatter/epub/templates_test.exs b/test/ex_doc/formatter/epub/templates_test.exs
index 9ce96b970..b69938fad 100644
--- a/test/ex_doc/formatter/epub/templates_test.exs
+++ b/test/ex_doc/formatter/epub/templates_test.exs
@@ -125,7 +125,7 @@ defmodule ExDoc.Formatter.EPUB.TemplatesTest do
       assert content =~ ~r{<title>CompiledWithDocs [^<]*</title>}
       assert content =~ ~r{<h1 id="content">\s*CompiledWithDocs\s*}
 
-      assert content =~ ~s{<h1 class="section-heading">Summary</h1>}
+      assert content =~ ~s{<h2 class="section-heading">Summary</h2>}
 
       assert content =~
                ~r{<h2 id="module-example-unicode-escaping">.*Example.*</h2>}ms

From 2d4d644d45cac7f115032950bc79fe07b556e2f5 Mon Sep 17 00:00:00 2001
From: David Oliver <david@doliver.co.uk>
Date: Mon, 26 Jan 2026 23:36:09 +0100
Subject: [PATCH 3/4] Improve distinction between docstring headings (H2-H4)

---
 assets/css/content/functions.css | 36 ++++++++++++++++----------------
 1 file changed, 18 insertions(+), 18 deletions(-)

diff --git a/assets/css/content/functions.css b/assets/css/content/functions.css
index 152398614..ca50e6e12 100644
--- a/assets/css/content/functions.css
+++ b/assets/css/content/functions.css
@@ -85,24 +85,24 @@ in both HTML and ePub. */
   }
 }
 
-.content-inner .docstring:is(h2, h3, h4, h5) {
-  font-weight: 700;
-}
-
-.content-inner .docstring h2 {
-  font-size: 1.1em;
-}
-
-.content-inner .docstring h3 {
-  font-size: 1em;
-}
-
-.content-inner .docstring h4 {
-  font-size: 0.95em;
-}
-
-.content-inner .docstring h5 {
-  font-size: 0.9em;
+/* Docstring headings */
+.content-inner .docstring {
+  & :is(h1, h2, h3, h4, h5, h6) {
+    font-weight: 700;
+    font-size: 1em;
+    margin-top: 2em;
+  }
+  /* h1 not expected */
+  & :is(h1, h2) {
+    font-size: 1.1em;
+  }
+  /* h4 the last level expected: smallcaps */
+  & :is(h4) {
+    font-size: .8em;
+    text-transform: uppercase;
+    letter-spacing: .1em;
+    color: var(--textBody);
+  }
 }
 
 .content-inner div.deprecated {

From 50759db69932341ee420a6a411440a5e24434ed0 Mon Sep 17 00:00:00 2001
From: David Oliver <david@doliver.co.uk>
Date: Tue, 27 Jan 2026 14:28:37 +0100
Subject: [PATCH 4/4] Turn whitespace minification back on

Previously, it seemed that esbuild was adding erroneous spaces in
':is(', but that isn't happening now. All minification is now enabled
whether in watch/dev mode or not, so that devs get the same results as a
production build. (Browsers do a good job of un-minifying for
inspection.)
---
 assets/build/build.js | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/assets/build/build.js b/assets/build/build.js
index 5e4f44946..839849199 100644
--- a/assets/build/build.js
+++ b/assets/build/build.js
@@ -46,10 +46,9 @@ Promise.all(formatters.map(async ({formatter, ...options}) => {
   const buildOptions = {
     entryNames: watchMode ? '[name]-dev' : '[name]-[hash]',
     bundle: true,
-    minifySyntax: !watchMode,
-    minifyIdentifiers: !watchMode,
-    // esbuild sometimes inserts erroneous space in ':is()' CSS function when whitespace minification is on: ': is()'
-    minifyWhitespace: false,
+    minifySyntax: true,
+    minifyIdentifiers: true,
+    minifyWhitespace: true,
     logLevel: watchMode ? 'warning' : 'info',
     ...options,
     plugins: [{