From b2a46333334e59a4a46d7de9d4ca39505848c9e1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=9B=B7=E7=94=B5=E8=8A=BD=E8=A1=A3?=
 <zhangyanghaha0407@outlook.com>
Date: Thu, 1 Oct 2026 11:52:29 -0400
Subject: [PATCH] =?UTF-8?q?T48a=20Docs=20=C2=B7=20Frame:=20titles=20and=20?=
 =?UTF-8?q?the=20list=20read=20plain=20words,=20links=20with=20a=20section?=
 =?UTF-8?q?=20route,=20long=20code=20wraps,=20the=20rail=20stays=20in=20fl?=
 =?UTF-8?q?ow=20on=20narrow=20screens,=20check.sh=20holds=20every=20docs?=
 =?UTF-8?q?=20example=20to=20Cargo.toml?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 frontend/src/docs/guides.ts | 16 ++++++++++------
 frontend/src/pages/Docs.tsx |  5 +++--
 frontend/src/styles.css     |  8 +++++---
 scripts/check.sh            |  4 ++++
 4 files changed, 22 insertions(+), 11 deletions(-)

diff --git a/frontend/src/docs/guides.ts b/frontend/src/docs/guides.ts
index f5bccfd..df5fab1 100644
--- a/frontend/src/docs/guides.ts
+++ b/frontend/src/docs/guides.ts
@@ -20,10 +20,12 @@ const escape = (text: string) => text.replace(/&/g, "&amp;").replace(/</g, "&lt;
 const slugify = (text: string) =>
   text
     .toLowerCase()
-    .replace(/<[^>]+>/g, "")
     .replace(/[^a-z0-9]+/g, "-")
     .replace(/^-|-$/g, "");
 
+/** A heading's words: no backticks, links as their text. */
+const plain = (markdown: string) => markdown.replace(/`/g, "").replace(/\[([^\]]*)\]\([^)]*\)/g, "$1");
+
 function read(file: string): Guide {
   const source = sources[`./${file}.md`];
   if (source === undefined) throw new Error(`docs: no ${file}.md`);
@@ -31,16 +33,18 @@ function read(file: string): Guide {
   const toc: Guide["toc"] = [];
   const marked = new Marked({
     renderer: {
-      heading({ tokens, depth }: Tokens.Heading) {
-        const html = this.parser.parseInline(tokens);
+      heading({ tokens, depth, text }: Tokens.Heading) {
+        const words = plain(text);
         if (depth === 1) {
-          title = html.replace(/<[^>]+>/g, "");
+          if (title) throw new Error(`docs: ${file}.md has a second # title`);
+          title = words;
           return "";
         }
-        const id = slugify(html);
+        const html = this.parser.parseInline(tokens);
+        const id = slugify(words);
         if (depth === 2) {
           if (toc.some((h) => h.id === id)) throw new Error(`docs: ${file}.md repeats heading ${id}`);
-          toc.push({ id, text: html.replace(/<[^>]+>/g, "") });
+          toc.push({ id, text: words });
         }
         return `<h${depth} id="${id}">${html}</h${depth}>`;
       },
diff --git a/frontend/src/pages/Docs.tsx b/frontend/src/pages/Docs.tsx
index 8ecb8fa..d998c79 100644
--- a/frontend/src/pages/Docs.tsx
+++ b/frontend/src/pages/Docs.tsx
@@ -37,7 +37,8 @@ export function Docs() {
     const link = target.closest<HTMLAnchorElement>("a[href^='/']");
     if (!link || e.metaKey || e.ctrlKey || e.shiftKey || e.button !== 0) return;
     e.preventDefault();
-    navigate({ to: link.getAttribute("href")! });
+    const url = new URL(link.href);
+    navigate({ to: url.pathname, hash: url.hash.slice(1) || undefined });
   };
 
   return (
@@ -66,7 +67,7 @@ export function Docs() {
         </nav>
       </article>
       {guide.toc.length > 0 && (
-        <nav className="doc-toc" aria-label="On this page">
+        <nav className="doc-toc" aria-label="On this page" data-lenis-prevent>
           <ol>
             {guide.toc.map((h) => (
               <li key={h.id}>
diff --git a/frontend/src/styles.css b/frontend/src/styles.css
index 65730bf..e2e7ac3 100644
--- a/frontend/src/styles.css
+++ b/frontend/src/styles.css
@@ -175,7 +175,7 @@ img.shot { display: block; max-width: 100%; height: auto; }
 .docs-rail a[aria-current="page"] { font-weight: 500; }
 .doc { padding: 96px 0 128px; min-width: 0; }
 .doc h1 { font-size: clamp(36px, 4vw, 56px); line-height: 1.05; font-weight: 800; letter-spacing: -0.035em; margin-bottom: 40px; }
-.prose { font-size: 17px; line-height: 30px; }
+.prose { font-size: 17px; line-height: 30px; overflow-wrap: anywhere; }
 .prose p, .prose li { color: color-mix(in srgb, var(--fg) 82%, var(--bg)); }
 .prose p { margin: 0 0 20px; }
 .prose h2 { font-size: 28px; line-height: 36px; font-weight: 700; letter-spacing: -0.02em; margin: 64px 0 16px; scroll-margin-top: 96px; }
@@ -207,8 +207,10 @@ img.shot { display: block; max-width: 100%; height: auto; }
 }
 
 @media (max-width: 1023px) {
-  .docs { grid-template-columns: minmax(0, 1fr); }
-  .docs-rail { display: none; }
+  .docs { grid-template-columns: minmax(0, 1fr); gap: 24px; }
+  .docs-rail { position: static; height: auto; padding: 96px 0 0; }
+  .docs-rail ol { display: flex; flex-wrap: wrap; gap: 4px 20px; }
+  .doc { padding-top: 48px; }
   .reader { grid-template-columns: minmax(0, 1fr); }
   .side { display: none; }
   .feature, .feature:nth-of-type(odd), .city { grid-template-columns: minmax(0, 1fr); grid-template-rows: none; gap: 32px; }
diff --git a/scripts/check.sh b/scripts/check.sh
index 6e092bc..cda9ada 100755
--- a/scripts/check.sh
+++ b/scripts/check.sh
@@ -27,4 +27,8 @@ deferred=$(grep -rn 'deferred(' src --include='*.rs' | grep -v '^src/primitives/
 [ -z "$deferred" ] || { echo "gpui deferred outside primitives::raise:"; echo "$deferred"; fail=1; }
 instant=$(grep -rnE '(^|[^_[:alnum:]])time::(Instant|\{[^}]*Instant)' src examples || true)
 [ -z "$instant" ] || { echo "std Instant panics in the browser, use web_time::Instant:"; echo "$instant"; fail=1; }
+for f in examples/docs/*.rs; do
+  n=$(basename "$f" .rs)
+  grep -qx "path = \"$f\"" Cargo.toml && grep -qx "name = \"docs_$n\"" Cargo.toml || { echo "$f needs [[example]] docs_$n in Cargo.toml"; fail=1; }
+done
 exit $fail