From faabb6d1aff54c7b52daad97a405ad3dd3134fe1 Mon Sep 17 00:00:00 2001
From: Jonathan Hefner <jonathan@hefner.pro>
Date: Mon, 9 Feb 2026 11:15:30 -0600
Subject: [PATCH] Apply `typedoc-github-theme` typography fixes locally via
 `customCss`

Backport the `.tsd-typography` CSS fixes from upstream PR
JulianWowra/typedoc-github-theme#7 so document pages render with
GitHub-accurate heading spacing, list bullets, line-height, and code
block overflow. The override file and `customCss` config can be removed
once the PR is merged and the dependency is updated.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 scripts/typedoc-github-theme-fixes.css | 117 +++++++++++++++++++++++++
 typedoc.config.mjs                     |   3 +
 2 files changed, 120 insertions(+)
 create mode 100644 scripts/typedoc-github-theme-fixes.css

diff --git a/scripts/typedoc-github-theme-fixes.css b/scripts/typedoc-github-theme-fixes.css
new file mode 100644
index 00000000..c1078be9
--- /dev/null
+++ b/scripts/typedoc-github-theme-fixes.css
@@ -0,0 +1,117 @@
+/**
+ * Local overrides for typedoc-github-theme typography styles.
+ *
+ * Upstream PR: https://github.com/JulianWowra/typedoc-github-theme/pull/7
+ *
+ * Remove this file once the PR is merged and the theme dependency is updated.
+ */
+
+/*
+ * Typography (all markdown content)
+ */
+
+.tsd-typography {
+	line-height: 1.5;
+}
+
+/* Underline plain links; TypeDoc adds classes to code refs and anchor icons */
+.tsd-typography a:not([class]),
+.tsd-typography a.external {
+	text-decoration: underline;
+}
+
+.tsd-typography code {
+	margin: 0;
+}
+
+.tsd-typography ul {
+	list-style: disc;
+}
+
+.tsd-typography ul ul {
+	list-style: circle;
+}
+
+.tsd-typography ul ul ul {
+	list-style: square;
+}
+
+.tsd-typography ul,
+.tsd-typography ol {
+	padding-left: 32px;
+}
+
+.tsd-typography pre {
+	padding: 16px;
+	overflow: auto;
+}
+
+.tsd-typography strong {
+	font-weight: 600;
+}
+
+/*
+ * Typography headings (document pages only)
+ *
+ * Heading styles are scoped to .tsd-panel.tsd-typography to avoid affecting
+ * JSDoc comment prose (.tsd-comment.tsd-typography) on API pages.
+ */
+
+/* Override heading margin for the first element (matches GitHub's markdown-body) */
+.tsd-panel.tsd-typography > :first-child {
+	margin-top: 0 !important;
+}
+
+.tsd-panel.tsd-typography h1,
+.tsd-panel.tsd-typography h2,
+.tsd-panel.tsd-typography h3,
+.tsd-panel.tsd-typography h4,
+.tsd-panel.tsd-typography h5,
+.tsd-panel.tsd-typography h6 {
+	margin-top: 24px;
+	margin-bottom: 16px;
+	font-weight: 600;
+	line-height: 1.25;
+}
+
+.tsd-panel.tsd-typography h1 {
+	font-size: 2em;
+	padding-bottom: 0.3em;
+	border-bottom: 1px solid var(--color-accent);
+}
+
+.tsd-panel.tsd-typography h2 {
+	font-size: 1.5em;
+	padding-bottom: 0.3em;
+	border-bottom: 1px solid var(--color-accent);
+}
+
+.tsd-panel.tsd-typography h3 {
+	font-size: 1.25em;
+}
+
+.tsd-panel.tsd-typography h4 {
+	font-size: 1em;
+}
+
+.tsd-panel.tsd-typography h5 {
+	font-size: 0.875em;
+}
+
+.tsd-panel.tsd-typography h6 {
+	font-size: 0.85em;
+	color: var(--color-text-aside);
+}
+
+.tsd-panel.tsd-typography > h1,
+.tsd-panel.tsd-typography > h2,
+.tsd-panel.tsd-typography > h3 {
+	margin-left: 0;
+	margin-right: 0;
+	padding: 0;
+}
+
+.tsd-panel.tsd-typography > h1,
+.tsd-panel.tsd-typography > h2 {
+	padding-bottom: 0.3em;
+}
diff --git a/typedoc.config.mjs b/typedoc.config.mjs
index e71dc294..06ff5c7e 100644
--- a/typedoc.config.mjs
+++ b/typedoc.config.mjs
@@ -46,6 +46,9 @@ const config = {
     "./scripts/typedoc-plugin-fix-mermaid-entities.mjs",
     "@boneskull/typedoc-plugin-mermaid",
   ],
+  // Remove once typedoc-github-theme merges upstream fix:
+  // https://github.com/JulianWowra/typedoc-github-theme/pull/7
+  customCss: "./scripts/typedoc-github-theme-fixes.css",
   ignoredHighlightLanguages: ["mermaid"],
 };