diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f3cfb9a..9baf328 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,13 +18,46 @@ example README, package README and user-facing command text. document fields, CLI commands, what each pack does with intent, and the published standards' files) are rendered by components in `components/reference/`. Change the code, not the page. -- Every page belongs to one of seven areas, each a folder whose `meta.json` - says `"root": true`. A folder in brackets, such as `how-to/(build)/`, - sets a page's area without changing its URL. A new page goes in its area's - folder and `meta.json`, and its URL into `test/page-urls.txt`; a page never - moves to a new URL without a redirect in `worker/redirects.js`. A section - that moves or is renamed keeps its old id with ``, - because a browser cannot redirect a fragment. +- Each platform has a site of its own, chosen with the picker in the header: + `synapse/`, `databricks/`, `adf/` and `duckdb/`, each with the same + sections (Get started, Guides, Standards, Connectors, then its own Concepts + and Reference pages). A section is a folder in brackets, such as + `synapse/(guides)/`, whose `meta.json` says `"root": true`; the brackets set + the tab without changing the URL, `/docs/synapse/`. The pages that + read the same everywhere (definitions, YAML, the command line, the editor, + errors) are in `concepts/` and `(reference)/`, one address each, with no + platform's text in them. `lib/platforms.ts` says which section and + platforms each page belongs to; `test/areas.test.ts` and + `test/platform-paths.test.ts` pin them. A page never moves to a new URL + without a redirect in `worker/redirects.js` or a page at the old URL that + lists its versions; a section that moves or is renamed keeps its old id + with ``, because a browser cannot redirect a fragment. +- A page several platforms show is written once, in `content/shared/`, and + each of those platforms has a stub: front matter and one ``, + nothing else. **Edit the shared file, never a stub**, and read a change to a + shared file on every platform that shows it. Text for some platforms goes + in `…`; a link to a page on the + reader's own platform is `/docs/~/`, and a component's + `platform="~"` is the page's platform. The build keeps only the page's + platform's text (`lib/remark-only.ts`), so its contents and search hold + nothing else. `test/stubs.test.ts` fails when a stub holds text of its own + or a product-wide page holds ``. +- **A platform's docs name no other platform**, in prose, YAML, commands, + outputs, alt text, links or examples. Each example on a platform's page is + that platform's own project; an example named `-~` is the page's + platform's, such as `data-products-synapse`. Data Factory into another + platform is a combined site of its own, `/docs/adf-`, listed + under **Combined** in the picker, and its pages may name its two + platforms. `test/platform-leak.test.ts` checks the pages' text and + `pnpm check:links` the built pages, components included; nothing is + allowed. Product-wide pages (Concepts, Reference, the home page) may name + every platform. Keep `` blocks out of list items: Prettier + re-indents them there. +- Connector pages are generated per platform: a connector's notes are one + file in `content/shared/connectors/`, and `pnpm stubs` writes each + platform's stubs, its Connectors `meta.json` and the old + `/docs/connectors/` pages from the connector facts. + `test/connector-sites.test.ts` fails when they are out of date. - A code block says what it is. `sh` fences are commands to run; `yaml`, `json`, `csv` and `dotenv` fences and `` files are files to write; an untitled `text` fence is what Ingestron prints; an `` under `build/` diff --git a/app/api/search/route.ts b/app/api/search/route.ts index ea164e1..4d1f4f9 100644 --- a/app/api/search/route.ts +++ b/app/api/search/route.ts @@ -1,12 +1,21 @@ import type { StructuredData } from "fumadocs-core/mdx-plugins"; import { createFromSource } from "fumadocs-core/search/server"; import { extraStructure, searchTitle } from "@/lib/search"; -import { source } from "@/lib/source"; +import { searchBreadcrumbs } from "@/lib/search-breadcrumbs"; +import { platformIds, platformOfPath } from "@/lib/platforms"; +import { movedGuide, source } from "@/lib/source"; // Exported once at build time as a static search index. Reference rendered // from code is added to its page's entries, so error codes and settings are found. +// A platform page is tagged with its platform and a shared page with every +// platform, so the dialog's platform filter keeps the shared sections. A +// guide's old URL, which only links to its versions, is left out. export const revalidate = false; -export const { staticGET: GET } = createFromSource(source, { +const indexed = { + ...source, + getPages: () => source.getPages().filter((page) => !movedGuide(page.path)), +}; +export const { staticGET: GET } = createFromSource(indexed as typeof source, { language: "english", buildIndex(page) { const own = page.data.structuredData as StructuredData; @@ -16,6 +25,9 @@ export const { staticGET: GET } = createFromSource(source, { description: page.data.description, url: page.url, id: page.url, + tag: platformOfPath(page.url) ?? [...platformIds], + // A platform's page starts with its platform, so the copies of a shared page differ. + breadcrumbs: searchBreadcrumbs(page.url, source.getPageTree()), structuredData: { headings: [...own.headings, ...extra.headings], contents: [...own.contents, ...extra.contents], diff --git a/app/content.css b/app/content.css index 81f7de8..5fb6ced 100644 --- a/app/content.css +++ b/app/content.css @@ -225,3 +225,20 @@ pre code > .line { display: block; margin-top: 0.3rem; } + +/* Above a platform page: which platform it is for, and the same page on the others. */ +/* A guide's old URL: one line per platform version. */ +.platform-chooser { + list-style: none; + padding: 0; +} +.platform-chooser li { + margin-block: 0.5rem; +} +.platform-chooser a { + font-weight: 600; +} +.platform-continue { + margin-block: 0 1rem; + font-weight: 600; +} diff --git a/app/docs/(areas)/[...slug]/page.tsx b/app/docs/(areas)/[...slug]/page.tsx index 38b296e..c16f2b4 100644 --- a/app/docs/(areas)/[...slug]/page.tsx +++ b/app/docs/(areas)/[...slug]/page.tsx @@ -5,25 +5,30 @@ import { getMDXComponents } from "@/components/mdx"; import { RelatedSetup } from "@/components/reference/related-setup"; import { catalogueToc, connectorToc } from "@/lib/connector-page"; import { connectorEntries } from "@/lib/reference"; -import { source } from "@/lib/source"; +import { platformOfPath, type Platform } from "@/lib/platforms"; +import { movedGuide, source } from "@/lib/source"; export default async function Page({ params }: { params: Promise<{ slug: string[] }> }) { const { slug } = await params; const page = source.getPage(slug); if (!page) notFound(); const MDX = page.data.body; - const id = slug[0] === "connectors" && slug.length === 2 ? slug[1] : undefined; + // A platform's connector page, /docs//connectors/, and its catalogue. + const platform = platformOfPath(slug.join("/")) as Platform["id"] | undefined; + const id = platform && slug[1] === "connectors" && slug.length === 3 ? slug[2] : undefined; const connector = id && connectorEntries(id).length ? id : undefined; - const related = connector ? : undefined; + const related = connector ? : undefined; // A connector page's headings come from its component, so its contents are built here. const toc = connector - ? connectorToc(connector, page.data.toc) - : slug.join("/") === "connectors" - ? catalogueToc(page.data.toc) + ? connectorToc(connector, page.data.toc, platform) + : platform && slug.length === 2 && slug[1] === "connectors" + ? catalogueToc(page.data.toc, platform) : page.data.toc; return ( // The breadcrumb starts at the page's area, such as "Connectors" on a connector's page. // tabIndex: the skip link focuses the article, so the next Tab is in it. [ + platform.id, + connectorsFor(platform.id).map((id) => ({ + id, + title: connectorEntries(id)[0]!.connector.title, + })), + ]), + ); return ( <> {/* The first stop on the page; the article it opens is #nd-page. */} , + }} tree={tree} tabs={tabs} tabMode="navbar" - sidebar={{ components: { Item: SidebarPageItem } }} + sidebar={{ + components: { Item: SidebarPageItem }, + banner: ( + <> + + + + ), + }} > + ({ url, urls: [...(urls ?? [])] }))} /> {children} diff --git a/app/docs/(hub)/layout.tsx b/app/docs/(hub)/layout.tsx index 4b3361f..d2d33de 100644 --- a/app/docs/(hub)/layout.tsx +++ b/app/docs/(hub)/layout.tsx @@ -1,26 +1,25 @@ import type { ReactNode } from "react"; import { HomeLayout } from "fumadocs-ui/layouts/home"; -import { getLayoutTabs } from "fumadocs-ui/layouts/shared"; import { SkipLink } from "@/components/keyboard"; import { baseOptions } from "@/lib/layout.shared"; -import { source } from "@/lib/source"; +import { platforms } from "@/lib/platforms"; // The home page is the hub: no sidebar and no contents, only the header. Where -// the other pages have their tab bar, its header has an Areas menu: seven -// links in a row would not fit beside the search at a laptop's width. +// the other pages have the platform picker and its tab bar, its header has a +// Platforms menu: each platform's docs, with the one line its card shows. export default function Layout({ children }: { children: ReactNode }) { const options = baseOptions(); - const areas = getLayoutTabs(source.getPageTree()).map((tab) => ({ - text: tab.title, - description: tab.description, - url: tab.url, + const items = platforms.map((platform) => ({ + text: platform.title, + description: platform.summary, + url: `/docs/${platform.id}`, })); return ( <> {children} diff --git a/app/docs/(hub)/page.tsx b/app/docs/(hub)/page.tsx index 13e6671..5dec494 100644 --- a/app/docs/(hub)/page.tsx +++ b/app/docs/(hub)/page.tsx @@ -3,15 +3,18 @@ import { notFound } from "next/navigation"; import { getMDXComponents } from "@/components/mdx"; import { AreaCards } from "@/components/hub"; import { HubSearch } from "@/components/hub-search"; -import { areaCards } from "@/lib/areas"; +import { areaCards, combinedAreas, platformAreas } from "@/lib/areas"; +import { ContinueWithPlatform } from "@/components/platform-choice"; import { source } from "@/lib/source"; -// The home page, /docs: search, a card for each area, then the two ways in -// and the value story from content/docs/index.mdx. +// The home page, /docs: search, a card for each platform, then the +// product-wide areas, then the ways in and the value story from +// content/docs/index.mdx. export default function Hub() { const page = source.getPage([]); if (!page) notFound(); const MDX = page.data.body; + const cards = areaCards(source.getPageTree()); return ( // The skip link's target; tabIndex so the next Tab is in the content.
@@ -23,10 +26,33 @@ export default function Hub() {
-
-

Choose an area

-

Each area has its own short menu.

- +
+

Choose your platform

+

+ Each platform has its own docs: getting started, guides, standards and connectors, with + nothing that does not apply to it. Not sure which?{" "} + Compare them, or try a sample on your + laptop with DuckDB: no cloud account needed. +

+ + platformAreas.includes(card.url))} /> +

Combined

+

+ Azure Data Factory copies the sources, and another platform keeps the tables. +

+ combinedAreas.includes(card.url))} /> +
+
+

For every platform

+

+ Definitions, YAML, the command line and the VS Code extension work the same on each + platform. +

+ !platformAreas.includes(card.url) && !combinedAreas.includes(card.url), + )} + />
diff --git a/app/hub.css b/app/hub.css index cbeaeaa..b3e72ad 100644 --- a/app/hub.css +++ b/app/hub.css @@ -144,6 +144,13 @@ font-weight: 750; letter-spacing: -0.02em; } +/* The combinations, under the platforms. */ +.hub-body > section > h3 { + margin: 2rem 0 0.3rem; + color: var(--docs-heading); + font-size: 1.125rem; + font-weight: 700; +} .hub-lead { margin: 0 0 1.25rem; color: var(--color-fd-muted-foreground); @@ -260,3 +267,8 @@ margin-top: 0; font-size: 1.1rem; } + +/* The platform cards, then everything else: a gap between the two groups. */ +.hub-body > section + section { + margin-top: 3rem; +} diff --git a/app/layout.tsx b/app/layout.tsx index 2b4b095..782cfb8 100644 --- a/app/layout.tsx +++ b/app/layout.tsx @@ -3,6 +3,8 @@ import type { ReactNode } from "react"; import { preload } from "react-dom"; import { RootProvider } from "fumadocs-ui/provider/next"; import { SearchFocusReturn } from "@/components/keyboard"; +import { PlatformSearchDialog } from "@/components/platform-search"; +import { siteScript } from "@/lib/site-script"; import "./global.css"; @@ -36,8 +38,15 @@ export default function Layout({ children }: { children: ReactNode }) { preload("/fonts/manrope-variable.woff2", { as: "font", type: "font/woff2", crossOrigin: "" }); return ( + + {/* Before the header paints: which platform's tabs to show + (lib/site-script.ts). Here, in the root layout, the server + renders it once; a page change does not render it again, and + PlatformMemory marks each page the reader moves to. */} +