Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
47 changes: 40 additions & 7 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<OldAnchor id="…" />`,
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/<page>`. 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 `<OldAnchor id="…" />`, 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 `<include>`,
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 `<Only on="synapse databricks">…</Only>`; a link to a page on the
reader's own platform is `/docs/~/<page>`, 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 `<Only>`.
- **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 `<name>-~` 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-<platform>`, 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 `<Only>` 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/<id>` 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 `<Example>` files are files to write; an
untitled `text` fence is what Ingestron prints; an `<Example>` under `build/`
Expand Down
16 changes: 14 additions & 2 deletions app/api/search/route.ts
Original file line number Diff line number Diff line change
@@ -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;
Expand All @@ -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],
Expand Down
17 changes: 17 additions & 0 deletions app/content.css
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}
19 changes: 13 additions & 6 deletions app/docs/(areas)/[...slug]/page.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -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/<platform>/connectors/<id>, 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 ? <RelatedSetup id={connector} /> : undefined;
const related = connector ? <RelatedSetup id={connector} platform={platform} /> : 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.
<DocsPage
// A guide's old URL is in no path, so it has no previous or next page.
footer={{ enabled: !movedGuide(page.path) }}
toc={toc}
tableOfContent={{ footer: related }}
breadcrumb={{ includeRoot: true }}
Expand Down Expand Up @@ -54,5 +59,7 @@ export async function generateMetadata({
title: page.data.title,
description: page.data.description,
alternates: { canonical: page.url },
// A guide's old URL only links to its platform versions.
...(movedGuide(page.path) && { robots: { index: false } }),
};
}
47 changes: 39 additions & 8 deletions app/docs/(areas)/layout.tsx
Original file line number Diff line number Diff line change
@@ -1,32 +1,63 @@
import type { ReactNode } from "react";
import { DocsLayout } from "fumadocs-ui/layouts/notebook";
import { ConnectorPicker } from "@/components/connector-picker";
import { AreaTabsCurrent, MenuDialog, SkipLink } from "@/components/keyboard";
import { PlatformMemory } from "@/components/platform-choice";
import { SidebarPageItem } from "@/components/sidebar-item";
import { areaTabs } from "@/lib/areas";
import { PlatformPicker } from "@/components/platform-picker";
import { SectionCompanion } from "@/components/section-companion";
import { companionData, headerTabs, siteSections } from "@/lib/areas";
import { baseOptions } from "@/lib/layout.shared";
import { platforms } from "@/lib/platforms";
import { connectorEntries, connectorsFor } from "@/lib/reference";
import { source } from "@/lib/source";

// Every page but the home page. Each area is a root folder in the page tree:
// the tab bar under the header picks the area, and the sidebar lists only that
// area's pages, less the connector pages (components/sidebar-item.tsx). Below
// the tab bar's width, the menu holds an area picker.
// Every page but the home page. The platform picker after the logo chooses
// whose docs you read; the tab row under the header holds that platform's
// sections, then Concepts and Reference. Each section is a root folder in the
// page tree, so the sidebar lists only its pages, less the connector pages
// (components/sidebar-item.tsx), which the connector picker finds.
export default function Layout({ children }: { children: ReactNode }) {
const options = baseOptions();
const tree = source.getPageTree();
const tabs = areaTabs(tree);
const tabs = headerTabs(tree);
// Each platform's connectors, for the picker at the top of its Connectors sidebar.
const pickerLists = Object.fromEntries(
platforms.map((platform) => [
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. */}
<SkipLink target="nd-page" />
<DocsLayout
{...options}
nav={{ ...options.nav, mode: "top" }}
nav={{
...options.nav,
mode: "top",
// The header puts this in a list of its own children, so it needs a key.
children: <PlatformPicker key="platform-picker" sites={siteSections(tree)} />,
}}
tree={tree}
tabs={tabs}
tabMode="navbar"
sidebar={{ components: { Item: SidebarPageItem } }}
sidebar={{
components: { Item: SidebarPageItem },
banner: (
<>
<ConnectorPicker lists={pickerLists} />
<SectionCompanion data={companionData(tree)} />
</>
),
}}
>
<MenuDialog />
<PlatformMemory />
<AreaTabsCurrent tabs={tabs.map(({ url, urls }) => ({ url, urls: [...(urls ?? [])] }))} />
{children}
</DocsLayout>
Expand Down
17 changes: 8 additions & 9 deletions app/docs/(hub)/layout.tsx
Original file line number Diff line number Diff line change
@@ -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 (
<>
<SkipLink target="hub" />
<HomeLayout
{...options}
links={[{ type: "menu", text: "Areas", items: areas }, ...(options.links ?? [])]}
links={[{ type: "menu", text: "Platforms", items }, ...(options.links ?? [])]}
>
{children}
</HomeLayout>
Expand Down
40 changes: 33 additions & 7 deletions app/docs/(hub)/page.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -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.
<div className="hub" id="hub" tabIndex={-1}>
Expand All @@ -23,10 +26,33 @@ export default function Hub() {
</div>
</section>
<div className="hub-width hub-body">
<section aria-labelledby="choose-an-area">
<h2 id="choose-an-area">Choose an area</h2>
<p className="hub-lead">Each area has its own short menu.</p>
<AreaCards cards={areaCards(source.getPageTree())} />
<section aria-labelledby="choose-a-platform">
<h2 id="choose-a-platform">Choose your platform</h2>
<p className="hub-lead">
Each platform has its own docs: getting started, guides, standards and connectors, with
nothing that does not apply to it. Not sure which?{" "}
<a href="/docs/concepts/choose-a-platform">Compare them</a>, or try a sample on your
laptop with <a href="/docs/duckdb/first-project">DuckDB</a>: no cloud account needed.
</p>
<ContinueWithPlatform />
<AreaCards cards={cards.filter((card) => platformAreas.includes(card.url))} />
<h3 id="combined">Combined</h3>
<p className="hub-lead">
Azure Data Factory copies the sources, and another platform keeps the tables.
</p>
<AreaCards cards={cards.filter((card) => combinedAreas.includes(card.url))} />
</section>
<section aria-labelledby="every-platform">
<h2 id="every-platform">For every platform</h2>
<p className="hub-lead">
Definitions, YAML, the command line and the VS Code extension work the same on each
platform.
</p>
<AreaCards
cards={cards.filter(
(card) => !platformAreas.includes(card.url) && !combinedAreas.includes(card.url),
)}
/>
</section>
<div className="prose hub-prose">
<MDX components={getMDXComponents()} />
Expand Down
12 changes: 12 additions & 0 deletions app/hub.css
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down Expand Up @@ -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;
}
11 changes: 10 additions & 1 deletion app/layout.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -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";

Expand Down Expand Up @@ -36,8 +38,15 @@ export default function Layout({ children }: { children: ReactNode }) {
preload("/fonts/manrope-variable.woff2", { as: "font", type: "font/woff2", crossOrigin: "" });
return (
<html lang="en-GB" suppressHydrationWarning>
<head>
{/* 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. */}
<script dangerouslySetInnerHTML={{ __html: siteScript() }} />
</head>
<body>
<RootProvider theme={{ enabled: true }} search={{ options: { type: "static" } }}>
<RootProvider theme={{ enabled: true }} search={{ SearchDialog: PlatformSearchDialog }}>
<SearchFocusReturn />
{children}
</RootProvider>
Expand Down
Loading
Loading