Refine Tabularium into a readable light documentation workspace

apps/docs/src/pages/docs/[slug].tsx

@@ -1,43 +1,235 @@
-import type { GetStaticPaths, GetStaticProps, InferGetStaticPropsType } from "next";
+import type {
+  GetStaticPaths,
+  GetStaticProps,
+  InferGetStaticPropsType,
+} from "next";
 import Head from "next/head";
 import Link from "next/link";
+import {
+  Children,
+  isValidElement,
+  useEffect,
+  useState,
+  type ReactNode,
+} from "react";
 import ReactMarkdown from "react-markdown";
 import remarkGfm from "remark-gfm";
 import { listDocs, readDoc, type Doc, type DocLink } from "@/lib/docs";
+import { Shell, Navigation } from "@/components/Shell";
+import { CodeBlock } from "@/components/CodeBlock";
+import { headingsFor, sectionFor } from "@/lib/navigation";
 
 type Props = { doc: Doc; docs: DocLink[] };
-
 export const getStaticPaths: GetStaticPaths = async () => ({
   paths: (await listDocs()).map(({ slug }) => ({ params: { slug } })),
   fallback: false,
 });
-
 export const getStaticProps: GetStaticProps<Props> = async ({ params }) => {
   const slug = params?.slug;
   if (typeof slug !== "string") return { notFound: true };
   const docs = await listDocs();
-  if (!docs.some((doc) => doc.slug === slug)) return { notFound: true };
+  if (!docs.some((d) => d.slug === slug)) return { notFound: true };
   return { props: { doc: await readDoc(slug), docs } };
 };
-
-export default function DocPage({ doc, docs }: InferGetStaticPropsType<typeof getStaticProps>) {
+function textOf(value: ReactNode): string {
+  return Children.toArray(value)
+    .map((child) =>
+      isValidElement<{ children?: ReactNode }>(child)
+        ? textOf(child.props.children)
+        : String(child),
+    )
+    .join("");
+}
+export default function DocPage({
+  doc,
+  docs,
+}: InferGetStaticPropsType<typeof getStaticProps>) {
+  const headings = headingsFor(doc.content);
+  const [active, setActive] = useState("");
+  const section = sectionFor(doc.slug);
+  const index = docs.findIndex((d) => d.slug === doc.slug);
+  useEffect(() => {
+    const observer = new IntersectionObserver(
+      (entries) => {
+        const visible = entries.filter((e) => e.isIntersecting);
+        if (visible[0]) setActive(visible[0].target.id);
+      },
+      { rootMargin: "-80px 0px -60% 0px" },
+    );
+    document
+      .querySelectorAll("article h2, article h3")
+      .forEach((el) => observer.observe(el));
+    return () => observer.disconnect();
+  }, [doc.slug]);
+  const toc = (
+    <nav aria-label="页内目录">
+      {headings.map((h) => (
+        <a
+          key={h.id}
+          href={`#${h.id}`}
+          className={`${h.level === 3 ? "toc-nested" : ""} ${active === h.id ? "active" : ""}`}
+          aria-current={active === h.id ? "location" : undefined}
+        >
+          {h.text}
+        </a>
+      ))}
+    </nav>
+  );
   return (
     <>
-      <Head><title>{doc.title} · Tabularium</title></Head>
-      <div className="mx-auto max-w-7xl px-6 py-8">
-        <header className="border-b border-stone-200 pb-6"><Link href="/" className="text-sm font-semibold tracking-widest">ENDOR / TABULARIUM</Link></header>
-        <a href="#content" className="sr-only focus:not-sr-only">跳到正文</a>
-        <div className="grid gap-10 py-10 md:grid-cols-[220px_minmax(0,1fr)] md:gap-16">
-          <nav aria-label="文档导航" className="flex flex-wrap gap-2 self-start md:sticky md:top-8 md:flex-col">
-            {docs.map((item) => <Link key={item.slug} href={`/docs/${item.slug}`} aria-current={item.slug === doc.slug ? "page" : undefined} className={`rounded-lg px-3 py-2 text-sm ${item.slug === doc.slug ? "bg-teal-50 font-medium text-teal-900" : "text-stone-600 hover:bg-stone-100"}`}>{item.title}</Link>)}
-          </nav>
-          <main id="content" className="min-w-0 max-w-3xl">
-            <article className="prose prose-stone max-w-none prose-headings:tracking-tight prose-a:text-teal-800 prose-pre:bg-stone-900 prose-img:rounded-xl">
-              <ReactMarkdown remarkPlugins={[remarkGfm]}>{doc.content}</ReactMarkdown>
+      <Head>
+        <title>{doc.title} · Tabularium</title>
+        <meta name="description" content={section.description} />
+      </Head>
+      <Shell key={doc.slug} docs={docs} current={doc.slug}>
+        <div className="reading-layout">
+          <aside className="sidebar">
+            <Navigation docs={docs} current={doc.slug} />
+          </aside>
+          <main id="content" className="reading-main">
+            <div className="breadcrumb">
+              <Link href="/">文档</Link>
+              <span>/</span>
+              <span>{section.group}</span>
+            </div>
+            <div className="article-meta">
+              <span className="eyebrow">{section.group}</span>
+              {doc.slug.includes("draft") && (
+                <span className="draft-badge">讨论草案</span>
+              )}
+            </div>
+            <article className="prose prose-neutral max-w-none">
+              <ReactMarkdown
+                remarkPlugins={[remarkGfm]}
+                components={{
+                  table: ({ children }) => (
+                    <div className="table-scroll">
+                      <table>{children}</table>
+                    </div>
+                  ),
+                  h1: ({ children }) => (
+                    <>
+                      <h1>{children}</h1>
+                      {headings.length > 0 && (
+                        <details className="mobile-toc">
+                          <summary>本页内容</summary>
+                          {toc}
+                        </details>
+                      )}
+                    </>
+                  ),
+                  h2: ({ children, node }) => {
+                    const h = headings.find(
+                      (h) => h.line === node?.position?.start.line,
+                    );
+                    return (
+                      <h2 id={h?.id}>
+                        <a className="heading-anchor" href={`#${h?.id}`}>
+                          {children}
+                          <span aria-hidden="true">#</span>
+                        </a>
+                      </h2>
+                    );
+                  },
+                  h3: ({ children, node }) => {
+                    const h = headings.find(
+                      (h) => h.line === node?.position?.start.line,
+                    );
+                    return (
+                      <h3 id={h?.id}>
+                        <a className="heading-anchor" href={`#${h?.id}`}>
+                          {children}
+                          <span aria-hidden="true">#</span>
+                        </a>
+                      </h3>
+                    );
+                  },
+                  pre: ({ children }) => {
+                    const child = Children.toArray(children)[0];
+                    if (
+                      isValidElement<{
+                        className?: string;
+                        children?: ReactNode;
+                      }>(child)
+                    )
+                      return (
+                        <CodeBlock
+                          code={textOf(child.props.children)}
+                          language={child.props.className?.replace(
+                            "language-",
+                            "",
+                          )}
+                        />
+                      );
+                    return <pre>{children}</pre>;
+                  },
+                  blockquote: ({ children }) => (
+                    <blockquote
+                      className={
+                        doc.slug.includes("draft")
+                          ? "callout callout-draft"
+                          : "callout"
+                      }
+                    >
+                      <span className="callout-icon" aria-hidden="true">
+                        ⓘ
+                      </span>
+                      <div>{children}</div>
+                    </blockquote>
+                  ),
+                }}
+              >
+                {doc.content}
+              </ReactMarkdown>
             </article>
+            <div className="article-end">
+              <span>文档与源码共同维护</span>
+              <a
+                href={`https://gitea.entroia.com/Zayden-Jung/endorphin-tabularium-docs/src/branch/main/content/docs/${doc.slug}.md`}
+              >
+                查看文档源码 ↗
+              </a>
+            </div>
+            <nav className="pagination" aria-label="相邻文档">
+              {index > 0 ? (
+                <Link href={`/docs/${docs[index - 1].slug}`}>
+                  <small>← 上一篇</small>
+                  <strong>{docs[index - 1].title}</strong>
+                </Link>
+              ) : (
+                <Link href="/">
+                  <small>← 返回</small>
+                  <strong>文档概览</strong>
+                </Link>
+              )}
+              {index < docs.length - 1 && (
+                <Link
+                  className="next-page"
+                  href={`/docs/${docs[index + 1].slug}`}
+                >
+                  <small>下一篇 →</small>
+                  <strong>{docs[index + 1].title}</strong>
+                </Link>
+              )}
+            </nav>
+            <footer className="article-footer">
+              ENDOR / TABULARIUM <span>记录思考，连接系统。</span>
+            </footer>
           </main>
+          <aside className="toc">
+            <p className="eyebrow">本页内容</p>
+            {toc}
+            <div className="toc-note">
+              <span className="status-dot" /> {section.label}
+              <p>
+                {doc.slug.includes("draft")
+                  ? "这里记录正在讨论的设计，尚不代表现有实现。"
+                  : "每一次理解，都成为下一步的起点。"}
+              </p>
+            </div>
+          </aside>
         </div>
-      </div>
+      </Shell>
     </>
   );
 }

apps/docs/src/pages/index.tsx

@@ -2,32 +2,167 @@ import type { GetStaticProps, InferGetStaticPropsType } from "next";
 import Head from "next/head";
 import Link from "next/link";
 import { listDocs, type DocLink } from "@/lib/docs";
+import { Shell, Navigation } from "@/components/Shell";
+import { CodeBlock } from "@/components/CodeBlock";
+import { sectionFor } from "@/lib/navigation";
 
-export const getStaticProps: GetStaticProps<{ docs: DocLink[] }> = async () => ({
-  props: { docs: await listDocs() },
-});
-
-export default function Home({ docs }: InferGetStaticPropsType<typeof getStaticProps>) {
+export const getStaticProps: GetStaticProps<{
+  docs: DocLink[];
+}> = async () => ({ props: { docs: await listDocs() } });
+export default function Home({
+  docs,
+}: InferGetStaticPropsType<typeof getStaticProps>) {
   return (
     <>
-      <Head><title>Tabularium · Endor 文档</title><meta name="description" content="Endor 的文档、架构设计与制图档案。" /></Head>
-      <main className="mx-auto max-w-5xl px-6 py-16 md:py-24">
-        <div className="flex items-center justify-between border-b border-stone-200 pb-6 text-sm">
-          <span className="font-semibold tracking-widest">ENDOR / TABULARIUM</span>
-          <span className="rounded-full border border-stone-200 px-3 py-1 text-stone-500">文档工作台</span>
+      <Head>
+        <title>Tabularium · Endor 文档</title>
+        <meta
+          name="description"
+          content="Endor 的知识档案。探索开发指南、架构设计与可复现的图形工作流。"
+        />
+      </Head>
+      <Shell docs={docs}>
+        <div className="home-layout">
+          <aside className="sidebar">
+            <Navigation docs={docs} />
+          </aside>
+          <main id="content" className="home-main">
+            <section className="home-hero">
+              <div className="hero-copy">
+                <p className="eyebrow">
+                  <span className="status-dot" /> ENDOR KNOWLEDGE ARCHIVE
+                </p>
+                <h1>
+                  理解系统。
+                  <br />
+                  构建下一步。
+                </h1>
+                <p className="hero-description">
+                  欢迎来到 <strong>Tabularium</strong>，Endor 的知识档案。
+                  <br className="desktop-break" />
+                  从第一篇文档到系统设计，让想法有迹可循。
+                </p>
+                <div className="hero-actions">
+                  <Link
+                    className="primary-button"
+                    href="/docs/01-getting-started"
+                  >
+                    开始阅读 <span>→</span>
+                  </Link>
+                  <a className="text-link" href="#explore">
+                    探索档案 <span>↓</span>
+                  </a>
+                </div>
+                <p className="hero-footnote">
+                  文档 · 架构 · 图形 <span>持续生长的工作台</span>
+                </p>
+              </div>
+              <div className="archive-visual" aria-hidden="true">
+                <div className="archive-grid" />
+                <div className="archive-caption">TABULARIUM / 001</div>
+                <div className="archive-sheet sheet-back">
+                  <span>03 — FIGURES</span>
+                  <i />
+                  <i />
+                  <i />
+                </div>
+                <div className="archive-sheet sheet-middle">
+                  <span>02 — ARCHITECTURE</span>
+                  <i />
+                  <i />
+                  <i />
+                </div>
+                <div className="archive-sheet sheet-front">
+                  <span className="sheet-label">01 / ENDOR</span>
+                  <div className="sheet-emblem">
+                    E<span>↗</span>
+                  </div>
+                  <div className="sheet-rule" />
+                  <b>Ideas, documented.</b>
+                  <small>知识在这里连接。</small>
+                </div>
+                <div className="archive-coordinate">
+                  文字与图形，一起演进 <span>↗</span>
+                </div>
+              </div>
+            </section>
+            <section className="explore-section" id="explore">
+              <div className="section-heading">
+                <div>
+                  <p className="eyebrow">EXPLORE THE ARCHIVE</p>
+                  <h2>从这里开始探索</h2>
+                </div>
+                <span className="section-count">
+                  {String(docs.length).padStart(2, "0")} 篇文档
+                </span>
+              </div>
+              <div className="doc-cards">
+                {docs.map((doc, index) => {
+                  const section = sectionFor(doc.slug);
+                  return (
+                    <Link
+                      className="doc-card"
+                      key={doc.slug}
+                      href={`/docs/${doc.slug}`}
+                    >
+                      <div className="card-top">
+                        <span className={`card-icon icon-${index}`}>
+                          {section.symbol}
+                        </span>
+                        <span className="card-number">0{index + 1}</span>
+                      </div>
+                      <p className="card-group">{section.group}</p>
+                      <h3>
+                        {doc.title.replace("（草案）", "")}
+                        <span aria-hidden="true">↗</span>
+                      </h3>
+                      <p className="card-description">{section.description}</p>
+                      <div className="card-bottom">
+                        <span>{section.label}</span>
+                        {doc.slug.includes("draft") && (
+                          <span className="draft-badge">草案</span>
+                        )}
+                      </div>
+                    </Link>
+                  );
+                })}
+              </div>
+            </section>
+            <section className="quickstart">
+              <div>
+                <p className="eyebrow">LOCAL WORKSPACE</p>
+                <h2>一个命令，继续探索。</h2>
+                <p>
+                  在本地启动文档工作台，
+                  <br />
+                  让文字和可复现的图形留在同一个仓库。
+                </p>
+                <Link
+                  className="text-link"
+                  href="/docs/01-getting-started#启动"
+                >
+                  查看完整启动指南 <span>→</span>
+                </Link>
+              </div>
+              <CodeBlock
+                language="sh"
+                code={
+                  "pnpm install --frozen-lockfile\nuv sync --project tools/figures --locked\npnpm dev\n"
+                }
+              />
+            </section>
+            <footer className="site-footer">
+              <span>
+                Endor / <strong>Tabularium</strong>
+              </span>
+              <span>记录思考，连接系统。</span>
+              <a href="https://gitea.entroia.com/Zayden-Jung/endorphin-tabularium-docs">
+                在仓库中探索 ↗
+              </a>
+            </footer>
+          </main>
         </div>
-        <p className="mt-16 text-sm tracking-widest text-teal-800">文档 · 设计 · 图形</p>
-        <h1 className="mt-4 text-5xl font-semibold tracking-tight md:text-7xl">Endor 的知识档案。</h1>
-        <p className="mt-6 max-w-2xl text-lg leading-8 text-stone-600">记录系统概念、架构讨论和开发约定，让文字与图形一起演进。</p>
-        <div className="mt-14 grid gap-4 md:grid-cols-2">
-          {docs.map((doc, index) => (
-            <Link key={doc.slug} href={`/docs/${doc.slug}`} className="group rounded-xl border border-stone-200 bg-white p-6 transition hover:border-teal-700 focus-visible:outline-2 focus-visible:outline-offset-4 focus-visible:outline-teal-700">
-              <span className="font-mono text-xs text-stone-400">{String(index + 1).padStart(2, "0")}</span>
-              <h2 className="mt-4 text-xl font-medium group-hover:text-teal-800">{doc.title} <span aria-hidden="true">↗</span></h2>
-            </Link>
-          ))}
-        </div>
-      </main>
+      </Shell>
     </>
   );
 }