diff --git a/apps/docs/scripts/build.ts b/apps/docs/scripts/build.ts index a1f51bc..3d28cc1 100644 --- a/apps/docs/scripts/build.ts +++ b/apps/docs/scripts/build.ts @@ -2,8 +2,8 @@ import { mkdir, readdir, rm } from "node:fs/promises" import { join } from "node:path" import { $ } from "bun" -import { appRoot, loadPages } from "./content" import { appRoot, loadPages, slugifyHeading } from "./content" +import { DEFAULT_SITE_URL } from "../src/lib/seo" await $`bun run ${join(appRoot, "scripts/check-content.ts")}` await $`bun run ${join(appRoot, "scripts/check-links.ts")}` @@ -68,14 +68,20 @@ function render(body: string) { } await rm(outputRoot, { recursive: true, force: true }) -const themeBootstrap = `` -const pageScript = `` -await rm(outputRoot, { recursive: true, force: true }) - const html = `${themeBootstrap}${escape(page.frontmatter.title)} · SO4 docs
SO4 docs

${escape(page.frontmatter.title)}

${render(page.body)}
${pageScript}` +// The docs stylesheet is the Vite bundle of `src/app/main.tsx` → +// `src/styles/globals.css` (Tailwind v4 + the shared `@workspace/ui` theme). +// Content pages link the hashed asset so they share one compiled stylesheet +// with the SPA home page. +await $`bunx vite build`.cwd(appRoot) +const stylesheet = (await readdir(join(outputRoot, "assets"))).find( + (file) => file.startsWith("index-") && file.endsWith(".css") +) +if (!stylesheet) throw new Error("Vite did not emit the docs stylesheet") + for (const page of pages) { const directory = join(outputRoot, page.route.slice(1)) await mkdir(directory, { recursive: true }) - const html = `${escape(page.frontmatter.title)} · SO4 docs
SO4 docsOpen interface

${escape(page.frontmatter.title)}

${render(page.body)}
` + const html = `${escape(page.frontmatter.title)} · SO4 docs
SO4 docsOpen interface

${escape(page.frontmatter.title)}

${render(page.body)}
` await Bun.write(join(directory, "index.html"), html) } diff --git a/apps/docs/scripts/check-content.ts b/apps/docs/scripts/check-content.ts index 6353834..4dd6f37 100644 --- a/apps/docs/scripts/check-content.ts +++ b/apps/docs/scripts/check-content.ts @@ -43,7 +43,10 @@ const navRoutes = meta.sections.flatMap((section) => for (const route of navRoutes) if (!routes.has(route)) errors.push(`sidebar references missing ${route}`) for (const route of routes) - if (!navRoutes.includes(route)) errors.push(`orphan page ${route}`) + // The home page is the site root — reachable by definition, not a sidebar + // entry — so it is exempt from the orphan check. + if (!navRoutes.includes(route) && route !== "/index") + errors.push(`orphan page ${route}`) const glossary = pages.find((page) => page.route === "/reference/glossary") if (!glossary) { @@ -56,8 +59,14 @@ if (!glossary) { ) if (titles.some((title, index) => title !== sorted[index])) errors.push("glossary is not alphabetical") + // `headingEntries` returns `{ title, id }` pairs, so each entry's onward + // link is found in its own section of the glossary body. + const sections = glossary.body.split(/\n(?=## )/) for (const entry of entries) { - const link = entry.answer.match(/\]\((\/[a-z0-9/#-]+)\)/)?.[1] + const section = sections.find((text) => + text.split("\n")[0].startsWith(`## ${entry.title}`), + ) + const link = section?.match(/\]\((\/[a-z0-9/#-]+)\)/)?.[1] if (!link) errors.push(`glossary#${entry.id}: missing onward link`) else if (!routes.has(link.split("#")[0])) errors.push(`glossary#${entry.id}: missing page ${link}`) diff --git a/apps/docs/scripts/components.test.tsx b/apps/docs/scripts/components.test.tsx index 4282cd5..a571e6f 100644 --- a/apps/docs/scripts/components.test.tsx +++ b/apps/docs/scripts/components.test.tsx @@ -223,6 +223,30 @@ test("MDX tabs sync groups, persist selection, and keep every panel", async () = expect(result.getByText("npm second")).toBeDefined() }) +test("MDX content tabs keep every panel mounted for print and search", () => { + const result = render( + + Bun instructions + npm instructions + + ) + + const panels = [...result.container.querySelectorAll("[data-tab-panel]")] + expect(panels.length).toBe(2) + expect(panels.map((panel) => panel.getAttribute("data-tab-label"))).toEqual([ + "bun", + "npm", + ]) + expect(panels[0].hidden).toBe(false) + expect(panels[1].hidden).toBe(true) + + // Only the `hidden` attribute separates the panels, so the print stylesheet + // can expand all of them without a beforeprint JS hook. + fireEvent.click(result.getByRole("button", { name: "npm" })) + expect(panels[0].hidden).toBe(true) + expect(panels[1].hidden).toBe(false) +}) + test("MDX tabs restore a persisted selection", async () => { window.localStorage.setItem("so4-docs-tabs:manager", "npm") const result = render() diff --git a/apps/docs/scripts/generate-faq.ts b/apps/docs/scripts/generate-faq.ts index e4fe300..dd66e13 100644 --- a/apps/docs/scripts/generate-faq.ts +++ b/apps/docs/scripts/generate-faq.ts @@ -5,16 +5,28 @@ import { headingEntries, loadPages } from "./content" const faq = (await loadPages()).find((page) => page.route === "/resources/faq") if (!faq) throw new Error("FAQ source is missing") const landing = new Set(faq.frontmatter.landing ?? []) +// `headingEntries` returns `{ title, id }` pairs, so each entry's answer text +// is taken from its own section of the FAQ body. +const sectionBodies = new Map( + faq.body + .split(/\n(?=## )/) + .filter((text) => text.startsWith("## ")) + .map((text) => [ + text.match(/\{#([a-z0-9-]+)\}/)?.[1], + text.slice(text.indexOf("\n") + 1).trim(), + ]), +) const entries = headingEntries(faq.body) .filter((entry) => landing.has(entry.id)) .map((entry) => { - const link = entry.answer.match(/\[([^\]]+)\]\(([^)]+)\)\.$/) + const answer = sectionBodies.get(entry.id) ?? "" + const link = answer.match(/\[([^\]]+)\]\(([^)]+)\)\.$/) if (!link) throw new Error(`FAQ ${entry.id} must end with one documentation link`) return { id: entry.id, question: entry.title, - answer: entry.answer.slice(0, link.index).trim(), + answer: answer.slice(0, link.index).trim(), linkLabel: link[1], href: link[2], } diff --git a/apps/docs/src/components/DocsLayout.tsx b/apps/docs/src/components/DocsLayout.tsx index 7d475fd..8c764e8 100644 --- a/apps/docs/src/components/DocsLayout.tsx +++ b/apps/docs/src/components/DocsLayout.tsx @@ -34,9 +34,15 @@ export function DocsLayout({ children, }: DocsLayoutProps) { return ( -
+
-
+
@@ -67,7 +73,10 @@ export function DocsLayout({
-
{footer ? ( -