astro.config.ts

import { readdir, readFile } from "node:fs/promises";
import { join } from "node:path";
import { fileURLToPath } from "node:url";
import { defineConfig } from "astro/config";
import react from "@astrojs/react";
import tailwindcss from "@tailwindcss/vite";
import icon from "astro-icon";
import skills from "astro-skills";
import nimbus, {
	defineConfig as defineNimbusConfig,
} from "@cloudflare/nimbus-docs";
import { hastPlugins } from "./src/plugins/satteri";
import { createSitemapLastmodSerializer } from "./sitemap.serializer";
import { isDisallowedByRobots } from "./src/util/robots";

// One sidebar section per top-level product directory, autogenerated from the
// shared content tree (mirrors CF's `autogenSections` in the Starlight config).
// `scope: "section"` then surfaces only the current product's tree per page;
// without the full set, off-pilot pages fell back to the whole configured list.
async function autogenSections() {
	const dirs = await readdir("./src/content/docs/", { withFileTypes: true });
	return dirs
		.filter((entry) => entry.isDirectory() && entry.name !== "agent-setup")
		.map((entry) => ({
			label: entry.name,
			items: [{ autogenerate: { directory: entry.name, collapsed: true } }],
		}));
}

async function getExternalLinkPaths(dir: string): Promise<Set<string>> {
	const paths = new Set<string>();
	const entries = await readdir(dir, { withFileTypes: true });

	for (const entry of entries) {
		const full = join(dir, entry.name);
		if (entry.isDirectory()) {
			for (const path of await getExternalLinkPaths(full)) {
				paths.add(path);
			}
		} else if (entry.name.endsWith(".mdx") || entry.name.endsWith(".md")) {
			const content = await readFile(full, "utf-8");
			const match = content.match(/^---\n([\s\S]*?)\n---/);
			if (match?.[1].includes("external_link:")) {
				let rel = full.slice("src/content/docs".length);
				rel = rel.replace(/\.(mdx|md)$/, "");
				rel = rel.replace(/\/index$/, "/");
				if (!rel.endsWith("/")) rel += "/";
				paths.add(rel.toLowerCase());
			}
		}
	}

	return paths;
}

const sidebarItems = await autogenSections();
const externalLinkPaths = await getExternalLinkPaths("src/content/docs");
const serializeSitemapLastmod = createSitemapLastmodSerializer();

// Mirrors production's sitemap `filter` (root astro.config.ts).
function isExcludedFromSitemap(url: string): boolean {
	if (url.includes("/style-guide/")) return true;
	if (url.endsWith("/404/")) return true;

	const pathname = new URL(url).pathname;
	if (externalLinkPaths.has(pathname)) return true;
	if (isDisallowedByRobots(pathname)) return true;

	return false;
}

// Resolved against this file (project root).
const here = (p: string) =>
	fileURLToPath(new URL(p, import.meta.url)).replace(/\/$/, "");

const nimbusConfig = defineNimbusConfig({
	site: "https://developers.cloudflare.com",
	title: "Cloudflare Docs",
	description: "Cloudflare's documentation.",
	locale: "en",
	github: "https://github.com/cloudflare/cloudflare-docs",
	editPattern:
		"https://github.com/cloudflare/cloudflare-docs/edit/production/{path}",
	socialImage: "/og-docs.png",
	socialImageAlt: "Cloudflare Docs",
	// "custom" renders the search UI slot but skips the built-in Pagefind index;
	// Nimbus mounts Algolia DocSearch instead (see ui/search/DocSearch.astro).
	search: { provider: "custom" },
	sidebar: {
		items: sidebarItems,
		overviewLabel: "Overview",
		indexDisplay: "overview-leaf",
		scope: "section",
		defaultCollapsed: true,
	},
});

// Maps Starlight icon names used in shared content to the iconify sets we ship,
// without touching content on disk: a pre-stage, MDX-scoped string rewrite.
const iconAlias = {
	name: "cf-nimbus:icon-alias",
	enforce: "pre" as const,
	transform(code: string, id: string) {
		const [pathOnly] = id.split("?", 1);
		if (!pathOnly?.endsWith(".mdx") && !pathOnly?.endsWith(".md")) return null;
		if (!/icon\s*=/.test(code)) return null;

		// Starlight ships a native `seti:` file-icon set; Nimbus routes icons
		// through astro-icon, which has no `seti` set. Map every `seti:` name the
		// shared content uses onto an installed set (vscode-icons / ph /
		// simple-icons). The substitute glyphs differ visually from Starlight's
		// seti set — a parity item tracked for the parity gate (Epic F), not a
		// render blocker.
		const SETI: Record<string, string> = {
			javascript: "vscode-icons:file-type-js-official",
			typescript: "vscode-icons:file-type-typescript-official",
			python: "vscode-icons:file-type-python",
			shell: "ph:terminal-window",
			rust: "vscode-icons:file-type-rust",
			video: "ph:play-circle",
			db: "ph:database",
			php: "vscode-icons:file-type-php",
			html: "vscode-icons:file-type-html",
			docker: "simple-icons:docker",
			svelte: "vscode-icons:file-type-svelte",
			powershell: "vscode-icons:file-type-powershell",
			notebook: "ph:notebook",
			nix: "vscode-icons:file-type-nix",
			json: "vscode-icons:file-type-json",
			java: "vscode-icons:file-type-java",
			go: "vscode-icons:file-type-go",
			"c-sharp": "vscode-icons:file-type-csharp",
			windows: "simple-icons:windows",
			linux: "simple-icons:linux",
			redhat: "simple-icons:redhat",
			debian: "simple-icons:debian",
			lock: "ph:lock",
			info: "ph:info",
			eye: "ph:eye",
			plan: "ph:file-text",
		};
		// Bare icon names (no set prefix) resolve against Starlight's built-in
		// icon set in the default build; under Nimbus they go through astro-icon
		// (local `src/icons` + installed iconify sets). Names not present locally
		// are mapped here onto an installed set. Glyphs differ visually from
		// Starlight's — a parity item for the parity gate (Epic F).
		const BARE: Record<string, string> = {
			document: "ph:file-text",
			"open-book": "ph:book-open",
			pen: "ph:pencil-simple",
			discord: "simple-icons:discord",
			"x.com": "simple-icons:x",
			apple: "ph:apple-logo",
			astro: "simple-icons:astro",
			bluesky: "simple-icons:bluesky",
			clock: "ph:clock",
			"comment-alt": "ph:chat-circle",
			connection: "ph:plugs-connected",
			database: "ph:database",
			download: "ph:download-simple",
			email: "ph:envelope-simple",
			error: "ph:warning-circle",
			external: "ph:arrow-square-out",
			github: "simple-icons:github",
			heart: "ph:heart",
			information: "ph:info",
			key: "ph:key",
			laptop: "ph:laptop",
			linux: "simple-icons:linux",
			"list-format": "ph:list-bullets",
			magnifier: "ph:magnifying-glass",
			mastodon: "simple-icons:mastodon",
			moon: "ph:moon",
			puzzle: "ph:puzzle-piece",
			rocket: "ph:rocket-launch",
			setting: "ph:gear",
			star: "ph:star",
			terminal: "ph:terminal-window",
		};

		let out = code;
		out = out.replace(/(["'])seti:([a-z0-9_-]+)\1/gi, (match, q, name) => {
			const mapped = SETI[name.toLowerCase()];
			return mapped ? `${q}${mapped}${q}` : match;
		});
		out = out.replace(
			/\bicon\s*=\s*(["'])([a-z0-9_.-]+)\1/gi,
			(match, q, name) => {
				if (name.includes(":")) return match;
				const mapped = BARE[name.toLowerCase()];
				return mapped ? `icon=${q}${mapped}${q}` : match;
			},
		);
		return out === code ? null : { code: out, map: null };
	},
};

const markdown = {
	syntaxHighlight: {
		type: "shiki" as const,
		excludeLangs: ["math", "mermaid"],
	},
	smartypants: false,
};

const integrations = [
	icon(),
	react(),
	// Injects /.well-known/agent-skills/* routes (index.json, SKILL.md, tarballs).
	skills(),
	nimbus(nimbusConfig, {
		mdx: { optimize: true },
		markdown: { hastPlugins },
		validateMdx: false,
		// Sitemap parity (T3): drop excluded URLs, stamp lastmod on the rest.
		sitemap: {
			serialize: async (item) =>
				isExcludedFromSitemap(item.url)
					? undefined
					: serializeSitemapLastmod(
							// nominal-only gap between nimbus-docs and @astrojs/sitemap types
							item as Parameters<typeof serializeSitemapLastmod>[0],
						),
		},
		// Partial resolution ( <Render file="..." product="..." /> ) is handled
		// entirely by our own Render.astro component via astro:content's
		// `getEntry("partials", id)` — no integration-level hook needed.
		rules: {
			"nimbus/frontmatter-shape": "error",
			"nimbus/image-ref": [
				"error",
				{ aliases: { "~/assets/": "src/assets/" } },
			],
			"nimbus/internal-link": "error",
		},
	}),
];

// Hint to the bundler that the components.ts re-export barrel has no module
// side effects, so unused named exports get tree-shaken instead of pulling
// in every component on every page.
const componentsBarrelId = normalizeId(here("./src/components.ts"));

function normalizeId(id: string) {
	return id.replace(/\\/g, "/").replace(/\?.*$/, "");
}

const componentsBarrelSideEffects = {
	name: "cf:components-barrel-side-effects",
	enforce: "pre" as const,
	transform: {
		filter: { id: /[\\/]components\.ts(?:\?.*)?$/ },
		handler(code: string, id: string) {
			if (normalizeId(id) !== componentsBarrelId) return;
			return { code, moduleSideEffects: false };
		},
	},
};

const appVite = {
	// Force a single React instance in case any dependency ships its own copy
	// of react/react-dom; without dedupe, Vite can load two React copies and
	// client islands fail to hydrate with "jsxDEV is not a function".
	resolve: { dedupe: ["react", "react-dom"] },
	plugins: [tailwindcss(), componentsBarrelSideEffects, iconAlias],
};

// https://astro.build/config
export default defineConfig({
	site: "https://developers.cloudflare.com",
	prefetch: {
		prefetchAll: true,
		defaultStrategy: "hover",
	},
	outDir: "./dist",
	cacheDir: ".astro-cache",
	markdown,
	image: {
		service: {
			entrypoint: "astro/assets/services/sharp",
			config: {
				limitInputPixels: false,
			},
		},
	},
	server: {
		port: 1111,
	},
	integrations,
	vite: {
		...appVite,
		server: {
			watch: {
				ignored: ["**/dist/**", "**/.astro-cache/**"],
			},
		},
	},
});