import { readdir, readFile } from "node:fs/promises";

import { join } from "node:path";

import { fileURLToPath } from "node:url";

import { defineConfig, envField, passthroughImageService } from "astro/config";

import react from "@astrojs/react";

import tailwindcss from "@tailwindcss/vite";

import nimbus, {

defineConfig as defineNimbusConfig,

} from "@cloudflare/nimbus-docs";

import { satteri } from "@astrojs/markdown-satteri";

import { hastPlugins } from "./src/plugins/satteri";

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");

// 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 AI Search instead (see ui/search/Search.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's icon system

// 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 the Icon

// component (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"],

},

};

const integrations = [

react(),

nimbus(nimbusConfig, {

mdx: { optimize: true },

markdown: {

processor: satteri({

features: { smartPunctuation: false },

hastPlugins,

}),

// Match Render.astro: `file` is relative to `src/content/partials/<product>/`.

// The revision invalidates prepared Markdown assets; bump it if this mapping changes.

partialResolver: {

revision: "partial-resolver-v1",

resolve: ({ file, product }) => (product ? `${product}/${file}` : file),

},

},

validateMdx: false,

// Nimbus sets `lastmod` from frontmatter or git; here we drop excluded

// URLs and escape `@` in the rest.

sitemap: {

serialize: (item) =>

isExcludedFromSitemap(item.url)

? undefined

: { ...item, url: item.url.replace(/@/g, "%40") },

},

rules: {

"nimbus/frontmatter-shape": "error",

"nimbus/image-ref": [

"error",

{ aliases: { "~/assets/": "src/assets/" } },

],

// Paths below are served by the Worker or another deployment, so the

// build's route list never contains them.

"nimbus/internal-link": [

"error",

{

ignore: [

"/api/**",

"/openapi.json",

"/.well-known/**",

"**/llms-full.txt",

"**/og.png",

"**/index.md",

// Model 404s are handled directly via custom worker/index.ts logic.

"/workers-ai/models/**",

"/ai/models/**",

],

},

],

// Reuses internal-link's `ignore` list.

"nimbus/redirected-link": "error",

},

// The Worker reads redirects from this file, not from `_redirects`.

redirectsFile: "public/__redirects",

}),

];

// 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",

env: {

schema: {

DEPLOYMENT_ENV: envField.enum({

context: "server",

access: "public",

values: ["preview", "production"],

default: "preview",

}),

},

},

experimental: {

incrementalBuild: process.env.INCREMENTAL_BUILD === "true" || false,

parallelPrerender:

process.env.PARALLEL_PRERENDER === "true"

? process.env.PARALLEL_WORKERS

? { workers: Number(process.env.PARALLEL_WORKERS) }

: true

: false,

},

markdown,

image: {

// /cdn-cgi/image/ only exists on Cloudflare's edge, so dev serves

// originals directly; production keeps edge resizing.

service:

process.env.NODE_ENV === "production"

? { entrypoint: "@astrojs/cloudflare/image-service" }

: passthroughImageService(),

},

server: {

port: 1111,

},

integrations,

vite: {

...appVite,

server: {

watch: {

ignored: ["**/dist/**"],

},

},

},

});