docs: rearchitect API reference into grouped multi-symbol pages

_components/Footer.tsx

@@ -59,7 +59,7 @@ const data = [
       },
       {
         label: "Deno API Reference",
-        href: "/api/deno/~/Deno",
+        href: "/api/deno/",
       },
     ],
   },

_components/SidebarNav/comp.tsx

@@ -4,7 +4,7 @@ import ReferenceSidebarNav from "../../reference/_components/ReferenceSidebarNav
 export default function (data: Lume.Data) {
   const sectionData = data.sectionData;
   const currentUrl = data.currentUrl.replace(/\/$/, "");
-  const isReference = currentUrl.startsWith("/api/");
+  const isReference = currentUrl === "/api" || currentUrl.startsWith("/api/");
 
   if (isReference) {
     return <ReferenceSidebarNav {...data} />;

_includes/layout.tsx

@@ -148,7 +148,7 @@ export default function Layout(data: Lume.Data) {
         />
         <div
           class={`layout ${
-            data.toc?.length || isReference
+            (data.toc?.length || isReference) && !data.fullWidth
               ? "layout--three-column"
               : "layout--two-column"
           }`}

_includes/reference/apiIndex.tsx

@@ -0,0 +1,73 @@
+import type { Group } from "../../reference/_lib/group.ts";
+
+export const layout = "doc.tsx";
+
+export interface ApiIndexData {
+  title: string;
+  intro: string;
+  aboutUrl: string;
+  aboutLabel: string;
+  allSymbolsUrl: string;
+  groups: { title: string; url: string; slug: string; group: Group }[];
+}
+
+/** Landing page for one API kind: a dense, Ctrl+F-able index of every symbol,
+ * grouped by category/module. Clicking a symbol jumps to its full docs on the
+ * grouped reference page. */
+export default function ApiIndex(
+  { data, comp }: { data: ApiIndexData } & Lume.Data,
+  _helpers: Lume.Helpers,
+) {
+  return (
+    <main id="content" className="ddoc markdown-body" tabIndex={-1}>
+      <div className="flex flex-wrap items-baseline justify-between gap-2">
+        <h1 className="!mb-0">{data.title}</h1>
+        <p className="!my-0 text-sm whitespace-nowrap">
+          <a href={data.aboutUrl}>{data.aboutLabel}</a>
+          {" · "}
+          <a href={data.allSymbolsUrl}>All symbols</a>
+        </p>
+      </div>
+      <p className="mt-2 max-w-prose text-foreground-secondary">
+        {data.intro}
+      </p>
+
+      {data.groups.map(({ title, url, slug, group }) => (
+        <section key={slug} className="mt-8">
+          <h2 id={slug} className="!mb-2 scroll-mt-16 !border-0">
+            <a href={url} className="!text-foreground-primary hover:underline">
+              {title}
+            </a>
+          </h2>
+          <ul className="!list-none !pl-0 !my-0">
+            {group.sections.flatMap((section) =>
+              section.nodes.map((node) => (
+                <li
+                  key={node.name}
+                  className="flex items-baseline gap-2 py-px !mt-0"
+                  aria-label={node.deprecated ? "deprecated" : undefined}
+                >
+                  <comp.DocNodeKindIcon kinds={node.doc_node_kind_ctx} />
+                  <a
+                    href={node.href}
+                    className={`font-mono text-sm whitespace-nowrap ${
+                      node.deprecated ? "line-through opacity-60" : ""
+                    }`}
+                  >
+                    {node.name}
+                  </a>
+                  {node.docs && (
+                    <div
+                      className="text-sm text-foreground-secondary line-clamp-1 [&_p]:inline [&_div]:inline min-w-0"
+                      dangerouslySetInnerHTML={{ __html: node.docs }}
+                    />
+                  )}
+                </li>
+              ))
+            )}
+          </ul>
+        </section>
+      ))}
+    </main>
+  );
+}

_includes/reference/landing.tsx

@@ -0,0 +1,86 @@
+export const layout = "doc.tsx";
+
+export interface LandingTile {
+  title: string;
+  href: string;
+  description: string | null;
+}
+
+export interface LandingSection {
+  key: string;
+  title: string;
+  description: string;
+  href: string;
+  allSymbolsHref: string;
+  tiles: LandingTile[];
+  /** Render tiles in a denser grid (used for the long Node module list). */
+  dense?: boolean;
+}
+
+export interface LandingData {
+  intro: string;
+  sections: LandingSection[];
+}
+
+/** The /api/ hub: every API group presented as a tile grid, generated from
+ * the same grouping data as the reference pages themselves. */
+export default function ApiLanding(
+  { data }: { data: LandingData } & Lume.Data,
+  _helpers: Lume.Helpers,
+) {
+  return (
+    <main
+      id="content"
+      className="ddoc markdown-body"
+      data-color-mode="auto"
+      data-light-theme="light"
+      data-dark-theme="dark"
+    >
+      <h1>API reference</h1>
+      <p className="max-w-prose text-foreground-secondary">{data.intro}</p>
+
+      {data.sections.map((section) => (
+        <section key={section.key} className="mt-10">
+          <header className="flex flex-wrap items-baseline justify-between gap-2">
+            <h2 className="!mb-0 !border-0">
+              <a href={section.href} className="!text-foreground-primary">
+                {section.title}
+              </a>
+            </h2>
+            <a
+              className="text-sm whitespace-nowrap"
+              href={section.allSymbolsHref}
+            >
+              View all symbols <span aria-hidden="true">-&gt;</span>
+            </a>
+          </header>
+          <p className="mt-2 max-w-prose text-foreground-secondary">
+            {section.description}
+          </p>
+          <div
+            className={`grid grid-cols-1 sm:grid-cols-2 gap-3 mt-4 ${
+              section.dense ? "lg:grid-cols-4" : "lg:grid-cols-3"
+            }`}
+          >
+            {section.tiles.map((tile) => (
+              <a
+                key={tile.href}
+                href={tile.href}
+                className="group flex flex-col gap-1 p-4 rounded-lg border border-foreground-tertiary !no-underline hover:border-primary transition-colors duration-150"
+              >
+                <span className="font-semibold !text-foreground-primary group-hover:underline underline-offset-4 decoration-primary">
+                  {tile.title}
+                </span>
+                {tile.description && (
+                  <span className="text-sm text-foreground-secondary">
+                    {tile.description}
+                  </span>
+                )}
+              </a>
+            ))}
+          </div>
+        </section>
+      ))}
+    </main>
+  );
+}

_includes/reference/multiSymbol.tsx

@@ -0,0 +1,52 @@
+import type { Group } from "../../reference/_lib/group.ts";
+
+export const layout = "doc.tsx";
+
+/** A grouped reference page: every symbol of a category (Deno, Web) or
+ * module (Node) documented on a single page — a symbol index up top,
+ * full documentation below. */
+export default function MultiSymbol(
+  { data, comp }: { data: Group } & Lume.Data,
+  _helpers: Lume.Helpers,
+) {
+  return (
+    <comp.Base data={{ breadcrumbs_ctx: data.breadcrumbs }} comp={comp}>
+      <div className="multiSymbolPage">
+        <header>
+          <h1 className="ref-h1">{data.title}</h1>
+          {data.docs && <div dangerouslySetInnerHTML={{ __html: data.docs }} />}
+          <comp.UsageLarge usages={data.usage} />
+        </header>
+
+        <section className="mt-8" id="symbol-index">
+          {data.sections.map((section) => (
+            <div className="mb-6">
+              <h2 className="ref-h2" id={section.anchor}>{section.title}</h2>
+              <comp.NamespaceSection namespaceSections={section.nodes} />
+            </div>
+          ))}
+        </section>
+
+        <hr className="my-10" />
+
+        <section id="symbol-docs">
+          {data.symbols.map((symbol) => (
+            <SymbolDivider comp={comp} symbol={symbol} />
+          ))}
+        </section>
+      </div>
+    </comp.Base>
+  );
+}
+
+function SymbolDivider(
+  // deno-lint-ignore no-explicit-any
+  { comp, symbol }: { comp: any; symbol: Group["symbols"][number] },
+) {
+  return (
+    <>
+      <comp.SymbolArticle symbol={symbol} />
+      <hr className="my-10 last:hidden" />
+    </>
+  );
+}

_includes/reference/preview.tsx

@@ -0,0 +1,124 @@
+import type {
+  PreviewMember,
+  PreviewSymbol,
+} from "../../reference/preview.page.ts";
+
+export const layout = "doc.tsx";
+
+interface PreviewData {
+  module: string;
+  usage: string;
+  symbols: PreviewSymbol[];
+  kindOrder: string[];
+  kindTitles: Record<string, string>;
+}
+
+/** PROTOTYPE layout: Node.js-docs-style prose-first rendering, fed from raw
+ * doc nodes instead of @deno/doc's pre-rendered HTML. */
+export default function Preview(
+  { data }: { data: PreviewData } & Lume.Data,
+  helpers: Lume.Helpers,
+) {
+  const md = (text: string | null) =>
+    text
+      ? (
+        <div
+          className="max-w-prose"
+          dangerouslySetInnerHTML={{ __html: helpers.md(text) }}
+        />
+      )
+      : null;
+
+  const sinceBadge = (since: string | null) =>
+    since && (
+      <p className="!mt-0 !mb-2 text-xs text-foreground-secondary">
+        Added in: {since}
+      </p>
+    );
+
+  const deprecatedBadge = (deprecated: string | null) =>
+    deprecated !== null && (
+      <div className="admonition caution">
+        <div className="title">Deprecated</div>
+        {md(deprecated || "This API is deprecated.")}
+      </div>
+    );
+
+  const member = (m: PreviewMember) => (
+    <section key={m.anchor} className="mt-6" id={m.anchor}>
+      <h4 className="!mb-1 scroll-mt-16">
+        <a href={`#${m.anchor}`} className="!text-foreground-primary">
+          <code>{m.signature}</code>
+        </a>
+      </h4>
+      {sinceBadge(m.since)}
+      {m.returnType && (
+        <p className="!my-1 text-sm text-foreground-secondary">
+          Returns: <code>{m.returnType}</code>
+        </p>
+      )}
+      {deprecatedBadge(m.deprecated)}
+      {md(m.doc)}
+    </section>
+  );
+
+  return (
+    <div className="ddoc markdown-body">
+      <main id="content" tabIndex={-1}>
+        <h1>
+          <code>node:{data.module}</code>
+        </h1>
+        <div className="admonition info">
+          <div className="title">Renderer preview</div>
+          <p>
+            This page is a prototype of rendering reference docs directly from
+            raw doc nodes, side by side with{" "}
+            <a href={`/api/node/${data.module}/`}>the current renderer</a>.
+          </p>
+        </div>
+        <pre><code>{data.usage}</code></pre>
+
+        {data.kindOrder.map((kind) => {
+          const group = data.symbols.filter((s) => s.kind === kind);
+          if (group.length === 0) return null;
+          return (
+            <section key={kind} className="mt-10">
+              <h2 id={`kind-${kind}`} className="scroll-mt-16">
+                {data.kindTitles[kind]}
+              </h2>
+              {group.map((symbol) => (
+                <article
+                  key={symbol.anchor}
+                  className="mt-8 pb-6 border-b border-foreground-tertiary"
+                  id={symbol.anchor}
+                >
+                  <h3 className="scroll-mt-16">
+                    <a
+                      href={`#${symbol.anchor}`}
+                      className="!text-foreground-primary"
+                    >
+                      <code>{symbol.heading}</code>
+                    </a>
+                  </h3>
+                  {sinceBadge(symbol.since)}
+                  {symbol.signature && (
+                    <pre><code>{symbol.signature}</code></pre>
+                  )}
+                  {symbol.returnType && symbol.kind !== "class" && (
+                    <p className="!my-1 text-sm text-foreground-secondary">
+                      {symbol.kind === "function" ? "Returns" : "Type"}:{" "}
+                      <code>{symbol.returnType}</code>
+                    </p>
+                  )}
+                  {deprecatedBadge(symbol.deprecated)}
+                  {md(symbol.doc)}
+                  {symbol.members.map(member)}
+                </article>
+              ))}
+            </section>
+          );
+        })}
+      </main>
+    </div>
+  );
+}

api/deno/index.md

@@ -2,6 +2,7 @@
 title: "Deno Namespace APIs"
 description: "A guide to Deno's built-in runtime APIs. Learn about file system operations, network functionality, permissions management, and other core capabilities available through the global Deno namespace."
 layout: doc.tsx
+url: /api/deno/about/
 oldUrl:
   - /runtime/manual/runtime/
   - /runtime/manual/runtime/builtin_apis/

api/node/index.md

@@ -2,6 +2,7 @@
 title: "Node.js Built-in APIs"
 description: "Complete reference for Node.js built-in modules and globals supported in Deno. Explore Node.js APIs including fs, http, crypto, process, buffer, and more with compatibility information."
 layout: doc.tsx
+url: /api/node/about/
 oldUrl:
   - /runtime/manual/node/compatibility/
   - /runtime/manual/npm_nodejs/compatibility_mode/

api/web/index.md

@@ -2,6 +2,7 @@
 title: "Web Platform APIs"
 description: "A guide to the Web Platform APIs available in Deno. Learn about fetch, events, workers, storage, and other web standard APIs, including implementation details and deviations from browser specifications."
 layout: doc.tsx
+url: /api/web/about/
 oldUrl:
   - /runtime/manual/runtime/navigator_api/
   - /runtime/manual/runtime/web_platform_apis/