From 70e45c80d933deecf2fb336f05470aa3983cf6cd Mon Sep 17 00:00:00 2001
From: Samuel Williams <samuel.williams@shopify.com>
Date: Sun, 16 Aug 2026 20:29:44 +1200
Subject: [PATCH] Summarize nested reference definitions

---
 pages/reference/show.xnode   | 18 +++++++++++++-----
 public/_static/site.css      | 31 +++++++++++++++++++++++++++++++
 test/utopia/project/serve.rb |  9 +++++++++
 3 files changed, 53 insertions(+), 5 deletions(-)

diff --git a/pages/reference/show.xnode b/pages/reference/show.xnode
index ec71309..11c23ca 100644
--- a/pages/reference/show.xnode
+++ b/pages/reference/show.xnode
@@ -30,13 +30,21 @@
 	if nested.any?
 	?>
 	<section>
-		<h2>Nested</h2>
+		<h2>Classes and Modules</h2>
 		
-		<ul>
-			<?r nested.each do |symbol| ?>
-			<li><a href="#{base.link_for(symbol)}"><code class="language-#{symbol.language.name}">#{symbol.nested_name}</code></a></li>
+		<dl class="nested-definitions">
+			<?r nested.each do |symbol|
+				documentation = symbol.documentation
+				if text = documentation&.text
+					description = text.take_while{|line| !line.empty?}.join("\n")
+				end
+			?>
+			<div>
+				<dt>#{partial 'content:declaration', symbol: symbol, link: true}</dt>
+				<dd><?r unless description&.empty? ?>#{base.format(description, symbol)}<?r end ?></dd>
+			</div>
 			<?r end ?>
-		</ul>
+		</dl>
 	</section>
 	<?r
 	end
diff --git a/public/_static/site.css b/public/_static/site.css
index f6f8b2a..d5ec5a8 100644
--- a/public/_static/site.css
+++ b/public/_static/site.css
@@ -437,6 +437,37 @@ dl.relationships dt, dl.relationships dd {
 	margin: 0;
 }
 
+dl.nested-definitions {
+	display: grid;
+	grid-template-columns: repeat(auto-fit, minmax(18rem, 1fr));
+	gap: 1.5rem 2rem;
+}
+
+dl.nested-definitions > div {
+	min-width: 0;
+}
+
+dl.nested-definitions dt, dl.nested-definitions dd,
+dl.nested-definitions dd p {
+	margin: 0;
+}
+
+dl.nested-definitions dt {
+	font-size: 1.05em;
+}
+
+dl.nested-definitions dt code,
+dl.nested-definitions dt syntax-code {
+	display: block;
+	max-width: 100%;
+	white-space: pre-wrap;
+	overflow-wrap: anywhere;
+}
+
+dl.nested-definitions dd {
+	margin-top: 0.25rem;
+}
+
 ul.index {
 	padding: 0;
 	list-style: none;
diff --git a/test/utopia/project/serve.rb b/test/utopia/project/serve.rb
index 7b70bb6..0e8419d 100644
--- a/test/utopia/project/serve.rb
+++ b/test/utopia/project/serve.rb
@@ -84,4 +84,13 @@
 		expect(body).to be(:include?, "<dt>Inherits from</dt>")
 		expect(body).to be(:include?, "/reference/Utopia/Project/Document/index#Utopia%3A%3AProject%3A%3ADocument%23root")
 	end
+	
+	it "summarizes nested definitions" do
+		body = client.get("/reference/Utopia/Project/index").read
+		
+		expect(body).to be(:include?, "Classes and Modules")
+		expect(body).to be(:include?, '<dl class="nested-definitions">')
+		expect(body).to be(:include?, '<a href="/reference/Utopia/Project/Document/index">class Document</a>')
+		expect(body).to be(:include?, "Represents a Markdown document with optional source code cross-references.")
+	end
 end