@ascribed/astro 0.2.1-next.14 → 0.2.1-next.16

package/README.md

@@ -16,13 +16,13 @@ import { defineConfig } from "astro/config";
 import ascribe from "@ascribed/astro";
 
 export default defineConfig({
-  site: "https://docs.example.com", // as in ascribe.toml's [consumer]
-  base: "/docs",
-  trailingSlash: "never",
+  // `site`, `base`, and `trailingSlash` come from ascribe.toml's [consumer].
   integrations: [ascribe({ build: "site" })],
 });
 ```
 
+Astro's `site`, `base`, and `trailingSlash` come from `ascribe.toml`'s `[consumer]` when the Astro config leaves them out. With `projects`, `site` and `trailingSlash` come from the first entry whose project sets them, and `base` stays the site's. Set in the Astro config, each must agree with `[consumer]`, or the build fails.
+
 ```ts
 // src/content.config.ts
 import { defineCollection } from "astro:content";
@@ -35,7 +35,7 @@ export const collections = { docs: defineCollection(ascribeCollection({ schema }
 
 If the Ascribe project is outside the Astro root (`project: "../docs"`), import `../.astro/integrations/_ascribed_astro/schema.ts` instead: the integration copies the schema there after each build, so TypeScript finds `astro/zod` from it.
 
-`[consumer] base-path` can be Astro's `base` or a path under it, so a home page can sit at `/` in front of docs at `/docs/`. Several projects can share one site, each under its own base path:
+`[consumer] base-path` can be Astro's `base` or a path under it, so a home page can sit at `/` in front of docs at `/docs/`: list the docs in `projects`, even alone, so Astro's `base` stays `/`. Several projects can share one site, each under its own base path:
 
 ```js
 ascribe({
@@ -52,15 +52,24 @@ ascribe({
 // A layout
 import Elements from "@ascribed/astro/Elements.astro";
 import Availability from "@ascribed/astro/Availability.astro";
+import Head from "@ascribed/astro/Head.astro";
 const { entry } = Astro.props;
 ---
-<head><Elements /></head>
+<head>
+  <!-- The title, description, canonical link, and robots rule, from the page's record. -->
+  <Head entry={entry} title={(title, record) => `${title} · Loom`} />
+  <Elements />
+</head>
 <Availability available={entry.data.available} />
 <!-- With `inline = "code"` on `title`: its code spans as <code>. -->
 <h1 set:html={entry.data.formatted.title} />
 ```
 
-The [Astro guide](https://ascribed-dev.com/guides/astro/) walks through a site: `ascribe.toml`, the collection, the route, the layout, the options, [a home page in front of the docs](https://ascribed-dev.com/guides/astro/#a-home-page-in-front-of-the-docs), [several projects in one site](https://ascribed-dev.com/guides/astro/#several-projects-in-one-site), what `astro dev` does, and [review in the site preview](https://ascribed-dev.com/guides/astro/#review-in-the-site-preview). [Review](https://ascribed-dev.com/guides/review/) walks through reviewing a pull request on your site.
+Each build writes a record of every page, `_ascribe/pages.json`, and the integration writes from every project's records what search engines read: `Head.astro` gives a page its `<title>`, description, canonical link, and `noindex` when it's `listing: unlisted`; and the site gets one `sitemap.xml`, at Astro's `base`, and one `robots.txt`, at the host's root, with each project's `[crawlers] lines`, in `astro build` and `astro dev`. A page with no record, such as an Astro page of the site's own, gets nothing from `Head.astro` and is in the sitemap as a page Astro built. A site with its own `public/robots.txt` or `public/sitemap.xml` keeps it, and a site whose `base` isn't `/` gets no `robots.txt`: the build prints the lines its host's needs. With no `site`, there's no sitemap.
+
+`npx @ascribed/astro init` writes those files into an Astro project once, as yours from then on: the collection (`src/content.config.ts`), the route (`src/pages/[...slug].astro`), a layout that loads the elements (`src/layouts/Docs.astro`), and the sidebar's list (`src/nav.ts`). It never writes over a file. `--project <dir>` names the folder holding `ascribe.toml`, and `--build <name>` the build, when there are several. The layout's sidebar comes from `sidebar(nav, entries)` in `@ascribed/astro/content`, which gives each listed page its entry and address, and fails the build when the list leaves out a page or names one that isn't there.
+
+The [Astro guide](https://ascribed-dev.com/go/astro-guide/) walks through a site: `ascribe.toml`, the collection, the route, the layout, the options, [a home page in front of the docs](https://ascribed-dev.com/go/a-home-page-in-front-of-the-docs/), [several projects in one site](https://ascribed-dev.com/go/several-projects-in-one-site/), search engines and crawlers, what `astro dev` does, and [review in the site preview](https://ascribed-dev.com/go/review-in-the-site-preview/). [Review](https://ascribed-dev.com/go/review-guide/) walks through reviewing a pull request on your site.
 
 ## Options
 
@@ -73,13 +82,16 @@ The [Astro guide](https://ascribed-dev.com/guides/astro/) walks through a site:
 | `anchors` | Source anchors (`ascribe build --anchors`), for review: `"dev"` in `astro dev` only, `true` always. By default, `false`, though `review` turns them on in `astro dev`. |
 | `review` | The **Ascribe review** app in `astro dev`'s toolbar: a pull request's changes and comments on the real page. `false` leaves it out. By default, `true`. Never in `astro build`. With `projects`, an entry's name reviews that entry, and `true` the first. |
 | `codeTitles` | A code block's title (`title="…"` in its info string, as `@snippet` writes it) above it: a Shiki transformer puts the block in a `<figure class="code-title">` with a `<figcaption>`. `false` leaves it out. By default, `true`. |
+| `sitemap` | `{ exclude: [...] }`: routes of the site's own pages, from the host's root, to leave out of the sitemap, such as one that carries `noindex`. |
 
 ## Development
 
 | File | Role |
 |---|---|
 | `src/index.ts` | The integration |
-| `src/content.ts` | `ascribeCollection`, for `content.config.ts` |
+| `src/content.ts` | `ascribeCollection`, for `content.config.ts`, and `sidebar`, for a layout |
+| `src/nav.ts` | The sidebar: entry ids, routes, and the check of the site's list against the collection |
+| `src/init.ts`, `src/cli.ts`, `starter/` | `npx @ascribed/astro init`, the package's command (`ascribe-astro`), and the files it writes. `examples/astro-site`'s are what it writes for that project; `test/init.test.ts` holds that, and rewrites them with `ASCRIBE_BLESS=1` |
 | `src/Elements.astro` | Loads `@ascribed/elements` (stylesheet and script) |
 | `src/Availability.astro` | A page's availability as the element library's badge |
 | `src/code-titles.ts` | The Shiki transformer that shows code block titles |

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+// `npx @ascribed/astro`: the package's command, `ascribe-astro`. Its one
+// subcommand, `init`, writes the starter (src/init.ts).
+import { parseArgs } from "node:util";
+import { init, STARTER_FILES } from "./init.js";
+const USAGE = `Usage: npx @ascribed/astro init [--project <dir>] [--build <name>]
+
+Writes the files every site built with Ascribe starts from into the Astro
+project in the current folder, once: ${STARTER_FILES.join(", ")}.
+It writes nothing if any of them is there.
+
+Options:
+  --project <dir>   The folder holding ascribe.toml, from the current folder. Default: the current folder.
+  --build <name>    The build the site shows. Default: the project's one build.
+  -h, --help        Print this.`;
+function main(argv) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            options: {
+                project: { type: "string" },
+                build: { type: "string" },
+                help: { type: "boolean", short: "h" },
+            },
+        });
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n\n${USAGE}\n`);
+        return 2;
+    }
+    const { values, positionals } = parsed;
+    if (values.help === true) {
+        process.stdout.write(`${USAGE}\n`);
+        return 0;
+    }
+    if (positionals.length !== 1 || positionals[0] !== "init") {
+        process.stderr.write(`${USAGE}\n`);
+        return 2;
+    }
+    return run(values.project, values.build);
+}
+async function run(project, build) {
+    try {
+        const result = await init({ root: process.cwd(), project, build });
+        const options = [`build: ${JSON.stringify(result.build)}`];
+        if (project !== undefined)
+            options.push(`project: ${JSON.stringify(project)}`);
+        process.stdout.write(`${result.written.map((file) => `wrote ${file}`).join("\n")}\n\n` +
+            `Next, if astro.config.mjs doesn't have it, add the integration:\n` +
+            `  integrations: [ascribe({ ${options.join(", ")} })],\n` +
+            `then run \`npx astro dev\`.\n`);
+        return 0;
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 2;
+    }
+}
+process.exitCode = await main(process.argv.slice(2));
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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","sourcesContent":["#!/usr/bin/env node\n// `npx @ascribed/astro`: the package's command, `ascribe-astro`. Its one\n// subcommand, `init`, writes the starter (src/init.ts).\nimport { parseArgs } from \"node:util\";\nimport { init, STARTER_FILES } from \"./init.js\";\n\nconst USAGE = `Usage: npx @ascribed/astro init [--project <dir>] [--build <name>]\n\nWrites the files every site built with Ascribe starts from into the Astro\nproject in the current folder, once: ${STARTER_FILES.join(\", \")}.\nIt writes nothing if any of them is there.\n\nOptions:\n  --project <dir>   The folder holding ascribe.toml, from the current folder. Default: the current folder.\n  --build <name>    The build the site shows. Default: the project's one build.\n  -h, --help        Print this.`;\n\nfunction main(argv: string[]): Promise<number> | number {\n  let parsed;\n  try {\n    parsed = parseArgs({\n      args: argv,\n      allowPositionals: true,\n      options: {\n        project: { type: \"string\" },\n        build: { type: \"string\" },\n        help: { type: \"boolean\", short: \"h\" },\n      },\n    });\n  } catch (error) {\n    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\\n\\n${USAGE}\\n`);\n    return 2;\n  }\n  const { values, positionals } = parsed;\n  if (values.help === true) {\n    process.stdout.write(`${USAGE}\\n`);\n    return 0;\n  }\n  if (positionals.length !== 1 || positionals[0] !== \"init\") {\n    process.stderr.write(`${USAGE}\\n`);\n    return 2;\n  }\n  return run(values.project, values.build);\n}\n\nasync function run(project: string | undefined, build: string | undefined): Promise<number> {\n  try {\n    const result = await init({ root: process.cwd(), project, build });\n    const options = [`build: ${JSON.stringify(result.build)}`];\n    if (project !== undefined) options.push(`project: ${JSON.stringify(project)}`);\n    process.stdout.write(\n      `${result.written.map((file) => `wrote ${file}`).join(\"\\n\")}\\n\\n` +\n        `Next, if astro.config.mjs doesn't have it, add the integration:\\n` +\n        `  integrations: [ascribe({ ${options.join(\", \")} })],\\n` +\n        `then run \\`npx astro dev\\`.\\n`,\n    );\n    return 0;\n  } catch (error) {\n    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\\n`);\n    return 2;\n  }\n}\n\nprocess.exitCode = await main(process.argv.slice(2));\n"]}

package/dist/content.d.ts

@@ -1,4 +1,8 @@
 import { glob } from "astro/loaders";
+import { type PageRecord } from "./records.js";
+import { type NavEntry, type NavGroup, type SidebarGroup } from "./nav.js";
+export type { NavGroup, SidebarGroup, SidebarPage } from "./nav.js";
+export type { Listing, PageRecord } from "./records.js";
 /**
  * The collection's loader and schema: the `glob` loader on the site output's
  * pages, with the generated Zod schema (`_ascribe/schema.ts`'s `schema`).
@@ -17,3 +21,25 @@ export declare function ascribeCollection<S>(options: {
     loader: ReturnType<typeof glob>;
     schema: S;
 };
+/**
+ * A layout's sidebar: `nav`'s groups, each page with its collection entry and
+ * its address, which is the one Ascribe's links use. `entries` is the
+ * collection (`await getCollection("docs")`), and `name` says which project's,
+ * as for `ascribeCollection`; with several projects and no `name`, it's the one
+ * the entries were loaded from. Throws, naming each, when `nav` leaves out a page
+ * of the collection, names a file that isn't one, or names a page twice, so the
+ * build fails until the list is complete.
+ */
+export declare function sidebar<E extends NavEntry>(nav: readonly NavGroup[], entries: readonly E[], options?: {
+    name?: string;
+}): SidebarGroup<E>[];
+/**
+ * A collection entry's page record, from its build's `_ascribe/pages.json`:
+ * its route, title, description, canonical address, and listing, as every
+ * output Ascribe writes has them. `undefined` for an entry that isn't from an
+ * Ascribe collection, or whose page has no record.
+ */
+export declare function pageRecord(entry: {
+    filePath?: string | undefined;
+    data?: unknown;
+}): PageRecord | undefined;

package/dist/content.js

@@ -13,10 +13,17 @@
 //   export const collections = {
 //     docs: defineCollection(ascribeCollection({ schema: docs, name: "docs" })),
 //   };
+//
+// A layout's sidebar, from the site's list of pages (`src/nav.ts`, which
+// `npx @ascribed/astro init` writes), checked against the collection:
+//
+//   const groups = sidebar(nav, await getCollection("docs"));
 import { pathToFileURL } from "node:url";
 import path from "node:path";
 import { glob } from "astro/loaders";
-import { collections, siteRoot } from "virtual:ascribe/site";
+import { astroRoot, collections, routes, siteRoot } from "virtual:ascribe/site";
+import { recordFor } from "./records.js";
+import { pageRoute, sidebarGroups, } from "./nav.js";
 /**
  * The collection's loader and schema: the `glob` loader on the site output's
  * pages, with the generated Zod schema (`_ascribe/schema.ts`'s `schema`).
@@ -33,6 +40,68 @@ export function ascribeCollection(options) {
     const base = pathToFileURL(rootFor(options.name) + path.sep);
     return { loader: glob({ pattern: ["**/*.md", "!_ascribe/**"], base }), schema: options.schema };
 }
+/**
+ * A layout's sidebar: `nav`'s groups, each page with its collection entry and
+ * its address, which is the one Ascribe's links use. `entries` is the
+ * collection (`await getCollection("docs")`), and `name` says which project's,
+ * as for `ascribeCollection`; with several projects and no `name`, it's the one
+ * the entries were loaded from. Throws, naming each, when `nav` leaves out a page
+ * of the collection, names a file that isn't one, or names a page twice, so the
+ * build fails until the list is complete.
+ */
+export function sidebar(nav, entries, options = {}) {
+    const root = sidebarRoot(entries, options.name);
+    const at = routes.find((route) => route.siteRoot === root);
+    const basePath = at?.basePath ?? "/";
+    const trailingSlash = at?.trailingSlash ?? "always";
+    return sidebarGroups(nav, entries, (id) => pageRoute(id, basePath, trailingSlash), (entry) => sourceFile(root, entry));
+}
+/**
+ * A collection entry's page record, from its build's `_ascribe/pages.json`:
+ * its route, title, description, canonical address, and listing, as every
+ * output Ascribe writes has them. `undefined` for an entry that isn't from an
+ * Ascribe collection, or whose page has no record.
+ */
+export function pageRecord(entry) {
+    if (entry.filePath === undefined)
+        return undefined;
+    const file = path.resolve(astroRoot, entry.filePath);
+    const roots = [...Object.values(collections), ...(siteRoot === "" ? [] : [siteRoot])];
+    const root = roots.find((candidate) => inside(candidate, file));
+    if (root === undefined)
+        return undefined;
+    const data = entry.data;
+    const source = typeof data?.source === "string"
+        ? data.source
+        : path.relative(root, file).split(path.sep).join("/");
+    return recordFor(root, source);
+}
+/**
+ * The site output root of the collection a sidebar lists: the entry `name`
+ * names, or, with several and no name, the one the entries were loaded from.
+ */
+function sidebarRoot(entries, name) {
+    const file = entries[0]?.filePath;
+    if (name === undefined && Object.keys(collections).length > 1 && file !== undefined) {
+        const from = Object.values(collections).find((root) => inside(root, file));
+        if (from !== undefined)
+            return from;
+    }
+    return rootFor(name);
+}
+/** Whether `file`, from the Astro root as an entry's `filePath` is, is under `root`. */
+function inside(root, file) {
+    const relative = path.relative(root, path.resolve(astroRoot, file));
+    return !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+/** An entry's source file, by its path in the site output, which mirrors the content root. */
+function sourceFile(root, entry) {
+    if (entry.filePath === undefined)
+        return `the page ${entry.id}`;
+    return inside(root, entry.filePath)
+        ? path.relative(root, path.resolve(astroRoot, entry.filePath)).split(path.sep).join("/")
+        : entry.filePath;
+}
 /** The site output root of the entry `name` names. */
 function rootFor(name) {
     const names = Object.keys(collections);

package/dist/content.js.map

@@ -1 +1 @@
-{"version":3,"file":"content.js","sourceRoot":"","sources":["../src/content.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,6EAA6E;AAC7E,2EAA2E;AAC3E,EAAE;AACF,sDAAsD;AACtD,iEAAiE;AACjE,6EAA6E;AAC7E,0FAA0F;AAC1F,EAAE;AACF,0DAA0D;AAC1D,EAAE;AACF,4FAA4F;AAC5F,iCAAiC;AACjC,iFAAiF;AACjF,OAAO;AACP,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AACrC,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAE7D;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAAI,OAAqC;IAIxE,iEAAiE;IACjE,MAAM,IAAI,GAAG,aAAa,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;IAC7D,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC,SAAS,EAAE,cAAc,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;AAClG,CAAC;AAED,sDAAsD;AACtD,SAAS,OAAO,CAAC,IAAwB;IACvC,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IACvC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CACb,0DAA0D,IAAI,qHAAqH,CACpL,CAAC;QACJ,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,WAAW,CAAC,KAAK,CAAC,CAAC,CAAW,CAAW,CAAC;QACzE,MAAM,IAAI,KAAK,CACb,mGAAmG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAC5I,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CACb,0DAA0D,IAAI,mCAAmC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAC1I,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC","sourcesContent":["// The content collection over a build's site output. Import it from\n// `content.config.ts`, which Vite loads, so it can read what the integration\n// resolved (`virtual:ascribe/site`) instead of finding the project itself.\n//\n//   import { defineCollection } from \"astro:content\";\n//   import { ascribeCollection } from \"@ascribed/astro/content\";\n//   import { schema } from \"../.ascribe/build/site/site/_ascribe/schema.ts\";\n//   export const collections = { docs: defineCollection(ascribeCollection({ schema })) };\n//\n// With several projects, each collection names its entry:\n//\n//   import { schema as docs } from \"../.astro/integrations/_ascribed_astro/docs/schema.ts\";\n//   export const collections = {\n//     docs: defineCollection(ascribeCollection({ schema: docs, name: \"docs\" })),\n//   };\nimport { pathToFileURL } from \"node:url\";\nimport path from \"node:path\";\nimport { glob } from \"astro/loaders\";\nimport { collections, siteRoot } from \"virtual:ascribe/site\";\n\n/**\n * The collection's loader and schema: the `glob` loader on the site output's\n * pages, with the generated Zod schema (`_ascribe/schema.ts`'s `schema`).\n * With several projects (`ascribe({ projects })`), `name` says which entry's\n * site output; it can be left out when there's one entry.\n *\n * Entry ids are Astro's own (`guides/my-setup` for `Guides/My Setup.md`, `index`\n * for the root page), which is what `AstroRouter` in `ascribe-resolve`\n * computes, so a page's route is the base path plus its id, and the root page is\n * at the base path itself.\n */\nexport function ascribeCollection<S>(options: { schema: S; name?: string }): {\n  loader: ReturnType<typeof glob>;\n  schema: S;\n} {\n  // `_ascribe/` holds the schema and published files, never pages.\n  const base = pathToFileURL(rootFor(options.name) + path.sep);\n  return { loader: glob({ pattern: [\"**/*.md\", \"!_ascribe/**\"], base }), schema: options.schema };\n}\n\n/** The site output root of the entry `name` names. */\nfunction rootFor(name: string | undefined): string {\n  const names = Object.keys(collections);\n  if (names.length === 0) {\n    if (name !== undefined) {\n      throw new Error(\n        `@ascribed/astro: ascribeCollection was given the name \"${name}\", but ascribe() was given one project, which has no name. Leave out \\`name\\`, or list the project in \\`projects\\`.`,\n      );\n    }\n    return siteRoot;\n  }\n  if (name === undefined) {\n    if (names.length === 1) return collections[names[0] as string] as string;\n    throw new Error(\n      `@ascribed/astro: ascribeCollection needs a \\`name\\` when ascribe() has several projects: one of ${names.map((n) => `\"${n}\"`).join(\", \")}.`,\n    );\n  }\n  const root = collections[name];\n  if (root === undefined) {\n    throw new Error(\n      `@ascribed/astro: ascribeCollection was given the name \"${name}\", and ascribe()'s projects are ${names.map((n) => `\"${n}\"`).join(\", \")}.`,\n    );\n  }\n  return root;\n}\n"]}
+{"version":3,"file":"content.js","sourceRoot":"","sources":["../src/content.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,6EAA6E;AAC7E,2EAA2E;AAC3E,EAAE;AACF,sDAAsD;AACtD,iEAAiE;AACjE,6EAA6E;AAC7E,0FAA0F;AAC1F,EAAE;AACF,0DAA0D;AAC1D,EAAE;AACF,4FAA4F;AAC5F,iCAAiC;AACjC,iFAAiF;AACjF,OAAO;AACP,EAAE;AACF,yEAAyE;AACzE,sEAAsE;AACtE,EAAE;AACF,8DAA8D;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AACrC,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChF,OAAO,EAAE,SAAS,EAAmB,MAAM,cAAc,CAAC;AAC1D,OAAO,EACL,SAAS,EACT,aAAa,GAId,MAAM,UAAU,CAAC;AAKlB;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAAI,OAAqC;IAIxE,iEAAiE;IACjE,MAAM,IAAI,GAAG,aAAa,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;IAC7D,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC,SAAS,EAAE,cAAc,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;AAClG,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,OAAO,CACrB,GAAwB,EACxB,OAAqB,EACrB,OAAO,GAAsB,EAAE;IAE/B,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC;IAC3D,MAAM,QAAQ,GAAG,EAAE,EAAE,QAAQ,IAAI,GAAG,CAAC;IACrC,MAAM,aAAa,GAAG,EAAE,EAAE,aAAa,IAAI,QAAQ,CAAC;IACpD,OAAO,aAAa,CAClB,GAAG,EACH,OAAO,EACP,CAAC,EAAE,EAAE,EAAE,CAAC,SAAS,CAAC,EAAE,EAAE,QAAQ,EAAE,aAAa,CAAC,EAC9C,CAAC,KAAK,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,EAAE,KAAK,CAAC,CACnC,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,KAG1B;IACC,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACnD,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IACrD,MAAM,KAAK,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,GAAG,CAAC,QAAQ,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IACtF,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC;IAChE,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACzC,MAAM,IAAI,GAAG,KAAK,CAAC,IAAwC,CAAC;IAC5D,MAAM,MAAM,GACV,OAAO,IAAI,EAAE,MAAM,KAAK,QAAQ;QAC9B,CAAC,CAAC,IAAI,CAAC,MAAM;QACb,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC1D,OAAO,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AACjC,CAAC;AAED;;;GAGG;AACH,SAAS,WAAW,CAAC,OAA4B,EAAE,IAAwB;IACzE,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC;IAClC,IAAI,IAAI,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACpF,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;QAC3E,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;IACtC,CAAC;IACD,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC;AACvB,CAAC;AAED,wFAAwF;AACxF,SAAS,MAAM,CAAC,IAAY,EAAE,IAAY;IACxC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC;IACpE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;AAClE,CAAC;AAED,8FAA8F;AAC9F,SAAS,UAAU,CAAC,IAAY,EAAE,KAAe;IAC/C,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS;QAAE,OAAO,YAAY,KAAK,CAAC,EAAE,EAAE,CAAC;IAChE,OAAO,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,QAAQ,CAAC;QACjC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;QACxF,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC;AACrB,CAAC;AAED,sDAAsD;AACtD,SAAS,OAAO,CAAC,IAAwB;IACvC,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IACvC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CACb,0DAA0D,IAAI,qHAAqH,CACpL,CAAC;QACJ,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,WAAW,CAAC,KAAK,CAAC,CAAC,CAAW,CAAW,CAAC;QACzE,MAAM,IAAI,KAAK,CACb,mGAAmG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAC5I,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CACb,0DAA0D,IAAI,mCAAmC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAC1I,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC","sourcesContent":["// The content collection over a build's site output. Import it from\n// `content.config.ts`, which Vite loads, so it can read what the integration\n// resolved (`virtual:ascribe/site`) instead of finding the project itself.\n//\n//   import { defineCollection } from \"astro:content\";\n//   import { ascribeCollection } from \"@ascribed/astro/content\";\n//   import { schema } from \"../.ascribe/build/site/site/_ascribe/schema.ts\";\n//   export const collections = { docs: defineCollection(ascribeCollection({ schema })) };\n//\n// With several projects, each collection names its entry:\n//\n//   import { schema as docs } from \"../.astro/integrations/_ascribed_astro/docs/schema.ts\";\n//   export const collections = {\n//     docs: defineCollection(ascribeCollection({ schema: docs, name: \"docs\" })),\n//   };\n//\n// A layout's sidebar, from the site's list of pages (`src/nav.ts`, which\n// `npx @ascribed/astro init` writes), checked against the collection:\n//\n//   const groups = sidebar(nav, await getCollection(\"docs\"));\nimport { pathToFileURL } from \"node:url\";\nimport path from \"node:path\";\nimport { glob } from \"astro/loaders\";\nimport { astroRoot, collections, routes, siteRoot } from \"virtual:ascribe/site\";\nimport { recordFor, type PageRecord } from \"./records.js\";\nimport {\n  pageRoute,\n  sidebarGroups,\n  type NavEntry,\n  type NavGroup,\n  type SidebarGroup,\n} from \"./nav.js\";\n\nexport type { NavGroup, SidebarGroup, SidebarPage } from \"./nav.js\";\nexport type { Listing, PageRecord } from \"./records.js\";\n\n/**\n * The collection's loader and schema: the `glob` loader on the site output's\n * pages, with the generated Zod schema (`_ascribe/schema.ts`'s `schema`).\n * With several projects (`ascribe({ projects })`), `name` says which entry's\n * site output; it can be left out when there's one entry.\n *\n * Entry ids are Astro's own (`guides/my-setup` for `Guides/My Setup.md`, `index`\n * for the root page), which is what `AstroRouter` in `ascribe-resolve`\n * computes, so a page's route is the base path plus its id, and the root page is\n * at the base path itself.\n */\nexport function ascribeCollection<S>(options: { schema: S; name?: string }): {\n  loader: ReturnType<typeof glob>;\n  schema: S;\n} {\n  // `_ascribe/` holds the schema and published files, never pages.\n  const base = pathToFileURL(rootFor(options.name) + path.sep);\n  return { loader: glob({ pattern: [\"**/*.md\", \"!_ascribe/**\"], base }), schema: options.schema };\n}\n\n/**\n * A layout's sidebar: `nav`'s groups, each page with its collection entry and\n * its address, which is the one Ascribe's links use. `entries` is the\n * collection (`await getCollection(\"docs\")`), and `name` says which project's,\n * as for `ascribeCollection`; with several projects and no `name`, it's the one\n * the entries were loaded from. Throws, naming each, when `nav` leaves out a page\n * of the collection, names a file that isn't one, or names a page twice, so the\n * build fails until the list is complete.\n */\nexport function sidebar<E extends NavEntry>(\n  nav: readonly NavGroup[],\n  entries: readonly E[],\n  options: { name?: string } = {},\n): SidebarGroup<E>[] {\n  const root = sidebarRoot(entries, options.name);\n  const at = routes.find((route) => route.siteRoot === root);\n  const basePath = at?.basePath ?? \"/\";\n  const trailingSlash = at?.trailingSlash ?? \"always\";\n  return sidebarGroups(\n    nav,\n    entries,\n    (id) => pageRoute(id, basePath, trailingSlash),\n    (entry) => sourceFile(root, entry),\n  );\n}\n\n/**\n * A collection entry's page record, from its build's `_ascribe/pages.json`:\n * its route, title, description, canonical address, and listing, as every\n * output Ascribe writes has them. `undefined` for an entry that isn't from an\n * Ascribe collection, or whose page has no record.\n */\nexport function pageRecord(entry: {\n  filePath?: string | undefined;\n  data?: unknown;\n}): PageRecord | undefined {\n  if (entry.filePath === undefined) return undefined;\n  const file = path.resolve(astroRoot, entry.filePath);\n  const roots = [...Object.values(collections), ...(siteRoot === \"\" ? [] : [siteRoot])];\n  const root = roots.find((candidate) => inside(candidate, file));\n  if (root === undefined) return undefined;\n  const data = entry.data as { source?: unknown } | undefined;\n  const source =\n    typeof data?.source === \"string\"\n      ? data.source\n      : path.relative(root, file).split(path.sep).join(\"/\");\n  return recordFor(root, source);\n}\n\n/**\n * The site output root of the collection a sidebar lists: the entry `name`\n * names, or, with several and no name, the one the entries were loaded from.\n */\nfunction sidebarRoot(entries: readonly NavEntry[], name: string | undefined): string {\n  const file = entries[0]?.filePath;\n  if (name === undefined && Object.keys(collections).length > 1 && file !== undefined) {\n    const from = Object.values(collections).find((root) => inside(root, file));\n    if (from !== undefined) return from;\n  }\n  return rootFor(name);\n}\n\n/** Whether `file`, from the Astro root as an entry's `filePath` is, is under `root`. */\nfunction inside(root: string, file: string): boolean {\n  const relative = path.relative(root, path.resolve(astroRoot, file));\n  return !relative.startsWith(\"..\") && !path.isAbsolute(relative);\n}\n\n/** An entry's source file, by its path in the site output, which mirrors the content root. */\nfunction sourceFile(root: string, entry: NavEntry): string {\n  if (entry.filePath === undefined) return `the page ${entry.id}`;\n  return inside(root, entry.filePath)\n    ? path.relative(root, path.resolve(astroRoot, entry.filePath)).split(path.sep).join(\"/\")\n    : entry.filePath;\n}\n\n/** The site output root of the entry `name` names. */\nfunction rootFor(name: string | undefined): string {\n  const names = Object.keys(collections);\n  if (names.length === 0) {\n    if (name !== undefined) {\n      throw new Error(\n        `@ascribed/astro: ascribeCollection was given the name \"${name}\", but ascribe() was given one project, which has no name. Leave out \\`name\\`, or list the project in \\`projects\\`.`,\n      );\n    }\n    return siteRoot;\n  }\n  if (name === undefined) {\n    if (names.length === 1) return collections[names[0] as string] as string;\n    throw new Error(\n      `@ascribed/astro: ascribeCollection needs a \\`name\\` when ascribe() has several projects: one of ${names.map((n) => `\"${n}\"`).join(\", \")}.`,\n    );\n  }\n  const root = collections[name];\n  if (root === undefined) {\n    throw new Error(\n      `@ascribed/astro: ascribeCollection was given the name \"${name}\", and ascribe()'s projects are ${names.map((n) => `\"${n}\"`).join(\", \")}.`,\n    );\n  }\n  return root;\n}\n"]}

package/dist/index.d.ts

@@ -30,6 +30,15 @@ interface SharedOptions {
      * `<figure class="code-title">` with a `<figcaption>`. Default `true`.
      */
     codeTitles?: boolean;
+    /**
+     * The site's one sitemap, at `<base>sitemap.xml`, of every listed page of
+     * every project and every page of the site's own. `exclude` lists routes,
+     * from the host's root, of the site's own pages to leave out of it, such
+     * as one that carries `noindex`.
+     */
+    sitemap?: {
+        exclude?: string[];
+    };
 }
 /** Options of the integration with one project. */
 export interface OneProjectOptions extends SharedOptions {
@@ -51,6 +60,7 @@ export type AscribeOptions = OneProjectOptions | ProjectsOptions;
 /**
  * Runs `ascribe build` for each project, checks the site's routing, adds the markdown plugin, adds a
  * page for each permalink's address, and serves published files, and, with `[consumer] agents = true`,
- * `llms.txt` and each page's Markdown, each at its project's base path.
+ * `llms.txt` and each page's Markdown, each at its project's base path; and writes the site's one
+ * sitemap and `robots.txt` from every project's page records.
  */
 export default function ascribe(options: AscribeOptions): AstroIntegration;

package/dist/index.js

@@ -4,7 +4,8 @@
 //   // astro.config.mjs
 //   import ascribe from "@ascribed/astro";
 //   export default defineConfig({
-//     base: "/docs", trailingSlash: "never",     // as in ascribe.toml's [consumer]
+//     // `site`, `base`, and `trailingSlash` come from ascribe.toml's
+//     // [consumer] when they're left out here; set here, they must agree.
 //     integrations: [ascribe({ build: "site" })],
 //   });
 //
@@ -19,6 +20,11 @@
 //   // a layout
 //   import Elements from "@ascribed/astro/Elements.astro";           // <Elements /> in <head>
 //   import Availability from "@ascribed/astro/Availability.astro";   // the page's availability
+//   import Head from "@ascribed/astro/Head.astro";                   // <Head entry={entry} /> in <head>
+//
+//   // the sidebar: src/nav.ts's list, checked against the collection
+//   import { sidebar } from "@ascribed/astro/content";
+//   const groups = sidebar(nav, await getCollection("docs"));
 //
 //   // src/pages/404.astro
 //   import MissingPermalink from "@ascribed/astro/MissingPermalink.astro"; // a permalink that isn't here
@@ -33,22 +39,25 @@
 //     review: "docs",
 //   })
 //   ascribeCollection({ schema, name: "docs" })
-import { mkdirSync } from "node:fs";
+import { existsSync, mkdirSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { findBinary } from "./binary.js";
 import { codeTitles } from "./code-titles.js";
 import { SeenFiles, watchDev } from "./dev.js";
 import { agentsMiddleware, copyAgentFiles, copyPublishedFiles, filesMiddleware, folderUnder, } from "./files.js";
-import { hasPermalinks, permalinkPattern, readPermalinks } from "./permalinks.js";
-import { consumerMismatches, homeRoute, readProject } from "./project.js";
+import { forwardingRoutes, hasPermalinks, permalinkPattern, readPermalinks } from "./permalinks.js";
+import { consumerMismatches, homeRoute, normalizeBase, readProject, supplyRouting, } from "./project.js";
 import { basePathClashes, nameProblems, pagesUnderOtherPaths, permalinkProblems, } from "./projects.js";
+import { pageList, readRecords, routeAs, routeKey, sitemapRoute } from "./records.js";
 import rehypeAscribeAttributes from "./rehype.js";
 import { removeDevFile, siteUrl, writeDevFile } from "./review/devfile.js";
 import { runDiff, runPrompt } from "./review/diff.js";
 import { APP_ID } from "./review/protocol.js";
 import { readRoutes } from "./review/routes.js";
 import { channelProblem, ReviewServer } from "./review/server.js";
+import { devRouted, devSitePages, rootFiles, rootFilesMiddleware, } from "./root-files.js";
 import { anchorsFor, hasWarnings, reviewFor, runBuild } from "./run.js";
 import { satteriAscribeAttributes } from "./satteri.js";
 import { copySchema } from "./schema.js";
@@ -65,7 +74,8 @@ function fail(problems, what) {
 /**
  * Runs `ascribe build` for each project, checks the site's routing, adds the markdown plugin, adds a
  * page for each permalink's address, and serves published files, and, with `[consumer] agents = true`,
- * `llms.txt` and each page's Markdown, each at its project's base path.
+ * `llms.txt` and each page's Markdown, each at its project's base path; and writes the site's one
+ * sitemap and `robots.txt` from every project's page records.
  */
 export default function ascribe(options) {
     /** With `projects`; otherwise the one entry has no name a collection gives. */
@@ -80,11 +90,44 @@ export default function ascribe(options) {
     let devCommand = false;
     let devHttps = false;
     let review;
+    /** The site's routes, as Astro resolved them, for what `astro dev` serves of the site's own. */
+    let astroRoutes = [];
+    /** The site's `public/` folder, where its own `robots.txt` would be. */
+    let publicDir = "";
+    /** What the sitemap and `robots.txt` are drawn from, given the site's pages and its routes. */
+    const rootSources = (sitePages, routed) => {
+        const base = routing?.base ?? "/";
+        const records = entries.map((entry) => readRecords(entry.siteRoot));
+        // Entries of one project share its `ascribe.toml`, and so its lines.
+        const lines = new Map();
+        for (const [i, entry] of entries.entries()) {
+            if (!lines.has(entry.project.dir))
+                lines.set(entry.project.dir, records[i]?.robots.lines ?? []);
+        }
+        const root = normalizeBase(base);
+        return {
+            projects: records.map(pageList),
+            routed,
+            sitePages,
+            excluded: [
+                ...forwardingRoutes(entries.map((entry) => readPermalinks(entry.siteRoot))),
+                `${root}404`,
+                `${root}500`,
+                ...(options.sitemap?.exclude ?? []),
+            ],
+            lines: [...lines.values()],
+            site: routing?.site,
+            base,
+            ownRobots: existsSync(path.join(publicDir, "robots.txt")),
+            ownSitemap: existsSync(path.join(publicDir, "sitemap.xml")),
+        };
+    };
     return {
         name: "@ascribed/astro",
         hooks: {
             "astro:config:setup": async ({ config, command, logger, updateConfig, addDevToolbarApp, createCodegenDir, injectRoute, }) => {
                 const root = fileURLToPath(config.root);
+                publicDir = fileURLToPath(config.publicDir);
                 const list = options.projects ?? [
                     {
                         name: "",
@@ -107,8 +150,11 @@ export default function ascribe(options) {
                         schemaDir: named ? path.join(codegen, entry.name) : codegen,
                     };
                 });
+                // What astro.config leaves unset comes from [consumer]: `site` and `trailingSlash` from the
+                // first project that has them, and with one project, `base` from its base path. With
+                // `projects`, `base` stays the site's, the root every base path is under.
+                const { routing: astro, supplied } = supplyRouting(entries.map((entry) => entry.project), { base: config.base, trailingSlash: config.trailingSlash, site: config.site }, !named);
                 // `ascribe.toml`'s routing must be Astro's, or every link Ascribe writes is wrong.
-                const astro = { base: config.base, trailingSlash: config.trailingSlash, site: config.site };
                 for (const entry of entries) {
                     fail(consumerMismatches(entry.project, astro), named
                         ? `"${entry.name}"'s ascribe.toml and astro.config disagree`
@@ -216,15 +262,16 @@ export default function ascribe(options) {
                     const served = lists.find(hasPermalinks) ?? lists[0];
                     if (served !== undefined) {
                         injectRoute({
-                            pattern: permalinkPattern(served.path, config.base),
+                            pattern: permalinkPattern(served.path, astro.base),
                             entrypoint: new URL("../src/Permalink.astro", import.meta.url),
                             prerender: true,
                         });
                     }
                 }
-                const projectHome = (entry) => homeRoute(entry.project.consumer.basePath, config.trailingSlash);
+                const projectHome = (entry) => homeRoute(entry.project.consumer.basePath, astro.trailingSlash);
                 // Dev serving of `_ascribe/files/`, and of the plain output for agents; the build copies them in `astro:build:done`.
                 updateConfig({
+                    ...supplied,
                     ...(options.codeTitles === false
                         ? {}
                         : { markdown: { shikiConfig: { transformers: [codeTitles] } } }),
@@ -237,9 +284,15 @@ export default function ascribe(options) {
                                 resolveId: (id) => (id === SITE_MODULE ? `\0${SITE_MODULE}` : undefined),
                                 load: (id) => id === `\0${SITE_MODULE}`
                                     ? `export const siteRoot = ${JSON.stringify(entries[0]?.siteRoot ?? "")};\n` +
-                                        `export const home = ${JSON.stringify(homeRoute(config.base, config.trailingSlash))};\n` +
+                                        `export const astroRoot = ${JSON.stringify(root)};\n` +
+                                        `export const home = ${JSON.stringify(homeRoute(astro.base, astro.trailingSlash))};\n` +
                                         `export const collections = ${JSON.stringify(named ? Object.fromEntries(entries.map((e) => [e.name, e.siteRoot])) : {})};\n` +
-                                        `export const permalinks = ${JSON.stringify(entries.map((e) => ({ siteRoot: e.siteRoot, home: projectHome(e) })))};`
+                                        `export const permalinks = ${JSON.stringify(entries.map((e) => ({ siteRoot: e.siteRoot, home: projectHome(e) })))};\n` +
+                                        `export const routes = ${JSON.stringify(entries.map((e) => ({
+                                            siteRoot: e.siteRoot,
+                                            basePath: e.project.consumer.basePath,
+                                            trailingSlash: e.project.consumer.trailingSlash,
+                                        })))};`
                                     : undefined,
                             },
                             {
@@ -251,12 +304,17 @@ export default function ascribe(options) {
                                         if (entry.agentsRoot !== undefined)
                                             server.middlewares.use(agentsMiddleware(entry.agentsRoot, base));
                                     }
+                                    // The sitemap and robots.txt, as the build would write them now.
+                                    server.middlewares.use(rootFilesMiddleware(astro.base, () => rootFiles(rootSources(devSitePages(astroRoutes, astro), devRouted(astroRoutes, astro)))));
                                 },
                             },
                         ],
                     },
                 });
             },
+            "astro:routes:resolved": ({ routes }) => {
+                astroRoutes = routes;
+            },
             "astro:server:setup": ({ server, refreshContent, logger, toolbar }) => {
                 if (!devCommand || !routing)
                     return;
@@ -331,8 +389,26 @@ export default function ascribe(options) {
                     for (const group of groups)
                         removeDevFile(group.project.dir, process.pid);
             },
-            "astro:build:done": async ({ dir, logger }) => {
+            "astro:build:done": async ({ dir, pages, logger }) => {
                 const base = routing?.base ?? "/";
+                const trailingSlash = routing?.trailingSlash ?? "ignore";
+                // Every page Astro built, by its route from the host's root. Astro lists
+                // pages only, not endpoints such as a feed, so a dot in a page's last
+                // segment, as in `/v1.2`, is still a page.
+                const built = pages.map((page) => routeAs(`${normalizeBase(base)}${page.pathname.replace(/^\//, "")}`, trailingSlash));
+                const builtKeys = new Set(built.map(routeKey));
+                const files = rootFiles(rootSources(built, (route) => builtKeys.has(routeKey(route))));
+                for (const note of files.notes)
+                    logger[note.level](note.text);
+                const out = fileURLToPath(dir);
+                if (files.sitemap !== undefined) {
+                    await writeFile(path.join(out, "sitemap.xml"), files.sitemap);
+                    logger.info(`wrote ${sitemapRoute(base)}`);
+                }
+                if (files.robots !== undefined) {
+                    await writeFile(path.join(out, "robots.txt"), files.robots);
+                    logger.info("wrote /robots.txt");
+                }
                 // Entries of one project publish at one base path: the first entry's copies go last, so they win.
                 for (const entry of [...entries].reverse()) {
                     const folder = folderUnder(entry.project.consumer.basePath, base);