docs: redesign landing hero, header, and footer

apps/docs/astro.config.mjs

@@ -13,18 +13,15 @@ export default defineConfig({
 			title: 'chkit Docs',
 			description: 'Public documentation for chkit, the ClickHouse schema and migration CLI.',
 			customCss: ['./src/styles/custom.css'],
-			...(isDev && {
-				components: {
-					Footer: './src/components/Footer.astro',
-				},
-			}),
+			components: {
+				Header: './src/components/Header.astro',
+				Hero: './src/components/Hero.astro',
+				Footer: './src/components/Footer.astro',
+				SiteTitle: './src/components/SiteTitle.astro',
+				SocialIcons: './src/components/SocialIcons.astro',
+				ThemeSelect: './src/components/ThemeSelect.astro',
+			},
 			sidebar: [
-				{
-					label: 'Overview',
-					items: [
-						{ label: 'Introduction', slug: 'index' },
-					],
-				},
 				{
 					label: 'Getting Started',
 					items: [

apps/docs/src/components/Footer.astro

@@ -1,8 +1,62 @@
 ---
+/**
+ * Override of Starlight's Footer.
+ * Renders the default per-page footer (pagination / meta) followed by the
+ * site-wide footer (brand + link columns). The Agentation overlay is
+ * rendered only under `import.meta.env.DEV`, so the production build drops
+ * it (and its react island) via dead-code elimination.
+ */
 import Default from '@astrojs/starlight/components/Footer.astro';
 import AgentationDev from './AgentationDev';
+
+const repo = 'https://github.com/obsessiondb/chkit';
 ---
 
 <Default><slot /></Default>
 
+<footer class="chk-site-footer not-content">
+	<div class="chk-site-footer-inner">
+		<div class="chk-footer-brand">
+			<a href="/" class="chk-wordmark chk-footer-wordmark"><span translate="no">ch-kit</span></a>
+			<p class="chk-footer-tagline">Headless TypeScript O(A)RM for ClickHouse!</p>
+			<div class="chk-footer-social">
+				<a href={repo} target="_blank" rel="noopener noreferrer" aria-label="GitHub">
+					<svg viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">
+						<path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8Z" />
+					</svg>
+				</a>
+				<a href="#" aria-label="Discord">
+					<svg viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+						<path d="M20.317 4.3698a19.7913 19.7913 0 00-4.8851-1.5152.0741.0741 0 00-.0785.0371c-.211.3753-.4447.8648-.6083 1.2495-1.8447-.2762-3.68-.2762-5.4868 0-.1636-.3933-.4058-.8742-.6177-1.2495a.077.077 0 00-.0785-.037 19.7363 19.7363 0 00-4.8852 1.515.0699.0699 0 00-.0321.0277C.5334 9.0458-.319 13.5799.0992 18.0578a.0824.0824 0 00.0312.0561c2.0528 1.5076 4.0413 2.4228 5.9929 3.0294a.0777.0777 0 00.0842-.0276c.4616-.6304.8731-1.2952 1.226-1.9942a.076.076 0 00-.0416-.1057c-.6528-.2476-1.2743-.5495-1.8722-.8923a.077.077 0 01-.0076-.1277c.1258-.0943.2517-.1923.3718-.2914a.0743.0743 0 01.0776-.0105c3.9278 1.7933 8.18 1.7933 12.0614 0a.0739.0739 0 01.0785.0095c.1202.099.246.1981.3728.2924a.077.077 0 01-.0066.1276 12.2986 12.2986 0 01-1.873.8914.0766.0766 0 00-.0407.1067c.3604.698.7719 1.3628 1.225 1.9932a.076.076 0 00.0842.0286c1.961-.6067 3.9495-1.5219 6.0023-3.0294a.077.077 0 00.0313-.0552c.5004-5.177-.8382-9.6739-3.5485-13.6604a.061.061 0 00-.0312-.0286zM8.02 15.3312c-1.1825 0-2.1569-1.0857-2.1569-2.419 0-1.3332.9555-2.4189 2.157-2.4189 1.2108 0 2.1757 1.0952 2.1568 2.419 0 1.3332-.9555 2.4189-2.1569 2.4189zm7.9748 0c-1.1825 0-2.1569-1.0857-2.1569-2.419 0-1.3332.9554-2.4189 2.1569-2.4189 1.2108 0 2.1757 1.0952 2.1568 2.419 0 1.3332-.946 2.4189-2.1568 2.4189Z" />
+					</svg>
+				</a>
+				<a href="#" aria-label="X">
+					<svg viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+						<path d="M18.901 1.153h3.68l-8.04 9.19L24 22.846h-7.406l-5.8-7.584-6.638 7.584H.474l8.6-9.83L0 1.154h7.594l5.243 6.932ZM17.61 20.644h2.039L6.486 3.24H4.298Z" />
+					</svg>
+				</a>
+			</div>
+		</div>
+
+		<div class="chk-footer-cols">
+			<div class="chk-footer-col">
+				<p class="chk-footer-col-title">Documentation</p>
+				<ul>
+					<li><a href="/getting-started/">Get started</a></li>
+					<li><a href="/cli/overview/">CLI reference</a></li>
+					<li><a href="/configuration/overview/">Configuration</a></li>
+					<li><a href="/schema/dsl-reference/">Schema</a></li>
+				</ul>
+			</div>
+			<div class="chk-footer-col">
+				<p class="chk-footer-col-title">Ports</p>
+				<ul>
+					<li><a href="https://npmx.dev/org/chkit" target="_blank" rel="noopener noreferrer">TypeScript</a></li>
+					<li><span class="chk-footer-soon">Python (coming soon)</span></li>
+				</ul>
+			</div>
+		</div>
+	</div>
+</footer>
+
 {import.meta.env.DEV && <AgentationDev client:only="react" />}

apps/docs/src/components/Header.astro

@@ -0,0 +1,52 @@
+---
+/**
+ * Override of Starlight's Header.
+ * Renders the default nav, then an ob-db-style breadcrumb subheader that
+ * spans the full width below the nav, above all three content columns.
+ * It is `position: fixed` (see .chk-subheader) so it escapes the nav box;
+ * the columns are offset downward by --chk-subheader-h in custom.css.
+ */
+import Default from '@astrojs/starlight/components/Header.astro';
+
+const { sidebar, entry } = Astro.locals.starlightRoute;
+const title = entry.data.title;
+const isSplash = entry.data.template === 'splash';
+
+type SidebarItem =
+	| { type: 'link'; label: string; isCurrent: boolean }
+	| { type: 'group'; label: string; entries: SidebarItem[] };
+
+function findGroupTrail(entries: SidebarItem[], trail: string[]): string[] | null {
+	for (const item of entries) {
+		if (item.type === 'group') {
+			const found = findGroupTrail(item.entries, [...trail, item.label]);
+			if (found) return found;
+		} else if (item.isCurrent) {
+			return trail;
+		}
+	}
+	return null;
+}
+
+const groups = isSplash ? [] : findGroupTrail(sidebar as SidebarItem[], []) ?? [];
+---
+
+<Default><slot /></Default>
+
+{
+	!isSplash && (
+		<div class="chk-subheader not-content">
+			<nav class="chk-breadcrumb" aria-label="Breadcrumb">
+				<a href="/">Docs</a>
+				{groups.map((g) => (
+					<>
+						<span class="chk-crumb-sep" aria-hidden="true">›</span>
+						<span>{g}</span>
+					</>
+				))}
+				<span class="chk-crumb-sep" aria-hidden="true">›</span>
+				<span class="chk-crumb-current">{title}</span>
+			</nav>
+		</div>
+	)
+}

apps/docs/src/components/Hero.astro

@@ -0,0 +1,212 @@
+---
+/**
+ * Override of Starlight's Hero (splash landing only).
+ * Same structure + frontmatter contract as the default Hero (title,
+ * tagline, image, actions), with a Drizzle-style "BACKED BY ObsessionDB"
+ * credit line under the copy. Visual styling lives in custom.css.
+ */
+import { Image } from 'astro:assets';
+import { LinkButton } from '@astrojs/starlight/components';
+
+const PAGE_TITLE_ID = '_top';
+
+const { data } = Astro.locals.starlightRoute.entry;
+const { title = data.title, tagline, image, actions = [] } = data.hero || {};
+
+const imageAttrs = {
+	loading: 'eager' as const,
+	decoding: 'async' as const,
+	width: 400,
+	height: 400,
+	alt: image?.alt || '',
+};
+
+let darkImage: ImageMetadata | undefined;
+let lightImage: ImageMetadata | undefined;
+let rawHtml: string | undefined;
+if (image) {
+	if ('file' in image) {
+		darkImage = image.file;
+	} else if ('dark' in image) {
+		darkImage = image.dark;
+		lightImage = image.light;
+	} else {
+		rawHtml = image.html;
+	}
+}
+---
+
+<div class="hero">
+	{
+		darkImage && (
+			<Image
+				src={darkImage}
+				{...imageAttrs}
+				class:list={{ 'light:sl-hidden': Boolean(lightImage) }}
+			/>
+		)
+	}
+	{lightImage && <Image src={lightImage} {...imageAttrs} class="dark:sl-hidden" />}
+	{rawHtml && <div class="hero-html sl-flex" set:html={rawHtml} />}
+	<div class="sl-flex stack">
+		<div class="sl-flex copy">
+			<h1 id={PAGE_TITLE_ID} data-page-title set:html={title} />
+			{tagline && <div class="tagline" set:html={tagline} />}
+			<p class="chk-backed">
+				<span>Backed by</span>
+				<a href="https://obsessiondb.com" target="_blank" rel="noopener noreferrer">
+					ObsessionDB
+				</a>
+			</p>
+			<div class="chk-badges">
+				<a
+					class="chk-badge"
+					href="https://npmx.dev/org/chkit"
+					target="_blank"
+					rel="noopener noreferrer"
+				>
+					<svg class="chk-badge-logo" viewBox="0 0 128 128" aria-hidden="true">
+						<path fill="#fff" d="M22.67 47h99.67v73.67H22.67z" />
+						<path
+							fill="#007acc"
+							d="M1.5 63.91v62.5h125v-125H1.5zm100.73-5a15.56 15.56 0 017.82 4.5 20.58 20.58 0 013 4c0 .16-5.4 3.81-8.69 5.85-.12.08-.6-.44-1.13-1.23a7.09 7.09 0 00-5.87-3.53c-3.79-.26-6.23 1.73-6.21 5a4.58 4.58 0 00.54 2.34c.83 1.73 2.38 2.76 7.24 4.86 8.95 3.85 12.78 6.39 15.16 10 2.66 4 3.25 10.46 1.45 15.24-2 5.2-6.9 8.73-13.83 9.9a38.32 38.32 0 01-9.52-.1 23 23 0 01-12.72-6.63c-1.15-1.27-3.39-4.58-3.25-4.82a9.34 9.34 0 011.15-.73L82 101l3.59-2.08.75 1.11a16.78 16.78 0 004.74 4.54c4 2.1 9.46 1.81 12.16-.62a5.43 5.43 0 00.69-6.92c-1-1.39-3-2.56-8.59-5-6.45-2.78-9.23-4.5-11.77-7.24a16.48 16.48 0 01-3.43-6.25 25 25 0 01-.22-8c1.33-6.23 6-10.58 12.82-11.87a31.66 31.66 0 019.49.26zm-29.34 5.24v5.12H56.66v46.23H45.15V69.26H28.88v-5a49.19 49.19 0 01.12-5.17C29.08 59 39 59 51 59h21.83z"
+						/>
+					</svg>
+					TypeScript
+				</a>
+				<a
+					class="chk-badge chk-badge--soon"
+					href="https://pypi.org/project/chkit-py/"
+					target="_blank"
+					rel="noopener noreferrer"
+				>
+					<svg class="chk-badge-logo" viewBox="0 0 128 128" aria-hidden="true">
+						<linearGradient
+							id="chk-py-a"
+							gradientUnits="userSpaceOnUse"
+							x1="70.252"
+							y1="1237.476"
+							x2="170.659"
+							y2="1151.089"
+							gradientTransform="matrix(.563 0 0 -.568 -29.215 707.817)"
+						>
+							<stop offset="0" stop-color="#5A9FD4" />
+							<stop offset="1" stop-color="#306998" />
+						</linearGradient>
+						<linearGradient
+							id="chk-py-b"
+							gradientUnits="userSpaceOnUse"
+							x1="209.474"
+							y1="1098.811"
+							x2="173.62"
+							y2="1149.537"
+							gradientTransform="matrix(.563 0 0 -.568 -29.215 707.817)"
+						>
+							<stop offset="0" stop-color="#FFD43B" />
+							<stop offset="1" stop-color="#FFE873" />
+						</linearGradient>
+						<path
+							fill="url(#chk-py-a)"
+							d="M63.391 1.988c-4.222.02-8.252.379-11.8 1.007-10.45 1.846-12.346 5.71-12.346 12.837v9.411h24.693v3.137H29.977c-7.176 0-13.46 4.313-15.426 12.521-2.268 9.405-2.368 15.275 0 25.096 1.755 7.311 5.947 12.519 13.124 12.519h8.491V67.234c0-8.151 7.051-15.34 15.426-15.34h24.665c6.866 0 12.346-5.654 12.346-12.548V15.833c0-6.693-5.646-11.72-12.346-12.837-4.244-.706-8.645-1.027-12.866-1.008zM50.037 9.557c2.55 0 4.634 2.117 4.634 4.721 0 2.593-2.083 4.69-4.634 4.69-2.56 0-4.633-2.097-4.633-4.69-.001-2.604 2.073-4.721 4.633-4.721z"
+							transform="translate(0 10.26)"
+						/>
+						<path
+							fill="url(#chk-py-b)"
+							d="M91.682 28.38v10.966c0 8.5-7.208 15.655-15.426 15.655H51.591c-6.756 0-12.346 5.783-12.346 12.549v23.515c0 6.691 5.818 10.628 12.346 12.547 7.816 2.297 15.312 2.713 24.665 0 6.216-1.801 12.346-5.423 12.346-12.547v-9.412H63.938v-3.138h37.012c7.176 0 9.852-5.005 12.348-12.519 2.578-7.735 2.467-15.174 0-25.096-1.774-7.145-5.161-12.521-12.348-12.521h-9.268zM77.809 87.927c2.561 0 4.634 2.097 4.634 4.692 0 2.602-2.074 4.719-4.634 4.719-2.55 0-4.633-2.117-4.633-4.719 0-2.595 2.083-4.692 4.633-4.692z"
+							transform="translate(0 10.26)"
+						/>
+					</svg>
+					Python
+					<span class="chk-badge-soon">Coming soon</span>
+				</a>
+			</div>
+		</div>
+		{
+			actions.length > 0 && (
+				<div class="chk-actions">
+					<p class="chk-actions-label">What you will find here</p>
+					<div class="sl-flex actions">
+						{actions.map(
+							({ attrs: { class: className, ...attrs } = {}, icon, link: href, text, variant }) => (
+								<LinkButton {href} {variant} icon={icon?.name} class:list={[className]} {...attrs}>
+									{text}
+									{icon?.html && <Fragment set:html={icon.html} />}
+								</LinkButton>
+							)
+						)}
+					</div>
+				</div>
+			)
+		}
+	</div>
+</div>
+
+<style>
+	/* Hero layout, ported from Starlight's default Hero (its scoped styles
+	   don't apply to this override). `.actions` is intentionally omitted —
+	   the Drizzle-style button grid is owned by custom.css. */
+	.hero {
+		display: grid;
+		align-items: center;
+		gap: 1rem;
+		padding-bottom: 1rem;
+	}
+
+	.hero > img,
+	.hero > .hero-html {
+		object-fit: contain;
+		width: min(70%, 20rem);
+		height: auto;
+		margin-inline: auto;
+	}
+
+	.stack {
+		flex-direction: column;
+		gap: clamp(1.5rem, calc(1.5rem + 1vw), 2rem);
+		text-align: center;
+	}
+
+	.copy {
+		flex-direction: column;
+		gap: 1rem;
+		align-items: center;
+	}
+
+	.copy > * {
+		max-width: 50ch;
+	}
+
+	h1 {
+		font-size: clamp(var(--sl-text-3xl), calc(0.25rem + 5vw), var(--sl-text-6xl));
+		line-height: var(--sl-line-height-headings);
+		font-weight: 600;
+		color: var(--sl-color-white);
+	}
+
+	.tagline {
+		font-size: clamp(var(--sl-text-base), calc(0.0625rem + 2vw), var(--sl-text-xl));
+		color: var(--sl-color-gray-2);
+	}
+
+	@media (min-width: 50rem) {
+		.hero {
+			grid-template-columns: 7fr 4fr;
+			gap: 3%;
+			padding-block: clamp(2.5rem, calc(1rem + 10vmin), 10rem);
+		}
+
+		.hero > img,
+		.hero > .hero-html {
+			order: 2;
+			width: min(100%, 25rem);
+		}
+
+		.stack {
+			text-align: start;
+		}
+
+		.copy {
+			align-items: flex-start;
+		}
+	}
+</style>