blume 2.1.0 → 2.1.2

package/src/search/sync/index.ts

@@ -1,3 +1,4 @@
+import { BlumeError } from "../../core/diagnostics.ts";
 import type { BlumeProject } from "../../core/project-graph.ts";
 import type { ResolvedSearchAdapter } from "../adapters/registry.ts";
 import { buildSearchDocuments, toSearchRecords } from "../documents.ts";
@@ -13,23 +14,49 @@ export interface SyncReporter {
   warn: (message: string) => void;
 }
 
+/** A hosted adapter's build-time sync. */
+interface HostedSync {
+  /** The env var holding the admin key the sync reads. */
+  key: string;
+  /**
+   * Whether the sync is set up to run: its admin key is set, and for Orama
+   * Cloud, the `indexId` that turns the sync on.
+   */
+  ready: boolean;
+  /** The upload, closed over the adapter's options. */
+  run: (records: SearchRecord[]) => Promise<void>;
+}
+
 /**
- * The sync a hosted adapter runs after a build, closed over its options, or
- * `null` for adapters with no in-process sync (static and Pagefind indexes are
- * built locally; Mixedbread syncs out-of-band via the `mxbai` CLI).
+ * The sync a hosted adapter runs after a build, or `null` for adapters with no
+ * in-process sync (static and Pagefind indexes are built locally; Mixedbread
+ * syncs out-of-band via the `mxbai` CLI).
  */
-const searchSync = (
-  provider: ResolvedSearchAdapter
-): ((records: SearchRecord[]) => Promise<void>) | null => {
+const searchSync = (provider: ResolvedSearchAdapter): HostedSync | null => {
   switch (provider.kind) {
     case "algolia": {
-      return (records) => syncAlgolia(records, provider.options);
+      const key = "ALGOLIA_ADMIN_API_KEY";
+      return {
+        key,
+        ready: Boolean(process.env[key]),
+        run: (records) => syncAlgolia(records, provider.options),
+      };
     }
     case "orama-cloud": {
-      return (records) => syncOramaCloud(records, provider.options);
+      const key = "ORAMA_PRIVATE_API_KEY";
+      return {
+        key,
+        ready: Boolean(process.env[key] && provider.options.indexId),
+        run: (records) => syncOramaCloud(records, provider.options),
+      };
     }
     case "typesense": {
-      return (records) => syncTypesense(records, provider.options);
+      const key = "TYPESENSE_ADMIN_API_KEY";
+      return {
+        key,
+        ready: Boolean(process.env[key]),
+        run: (records) => syncTypesense(records, provider.options),
+      };
     }
     default: {
       return null;
@@ -41,7 +68,9 @@ const searchSync = (
  * After a build, upload the per-page records to the configured hosted adapter.
  * Reads secret admin keys from the environment; if a key (or option) is
  * missing the sync is skipped with a warning rather than failing the build —
- * CI may sync in a separate step.
+ * a local build has no secrets, and CI may sync in a separate step. Once the
+ * sync is set up, a failure fails the build (`BLUME_SEARCH_SYNC_FAILED`):
+ * the site would otherwise deploy against an index this build didn't update.
  */
 export const syncSearchProvider = async (
   project: BlumeProject,
@@ -57,11 +86,21 @@ export const syncSearchProvider = async (
   reporter.start(`Syncing ${records.length} record(s) to ${provider.kind}`);
 
   try {
-    await sync(records);
+    await sync.run(records);
     reporter.success(`Synced ${records.length} record(s) to ${provider.kind}`);
   } catch (error) {
     // SAFETY: the three sync clients surface network/auth failures as Error
-    // instances; the message is read only to annotate the skip warning.
-    reporter.warn(`Search sync skipped: ${(error as Error).message}`);
+    // instances; the message is read only to annotate the warning or error.
+    const { message } = error as Error;
+    if (!sync.ready) {
+      reporter.warn(`Search sync skipped: ${message}`);
+      return;
+    }
+    throw new BlumeError({
+      code: "BLUME_SEARCH_SYNC_FAILED",
+      message: `Search sync to ${provider.kind} failed: ${message}`,
+      severity: "error",
+      suggestion: `Check ${sync.key} and the adapter's options, or unset ${sync.key} to build without syncing.`,
+    });
   }
 };

package/src/search/sync/typesense.ts

@@ -7,17 +7,44 @@ import type { SearchRecord } from "../documents.ts";
 /** The adapter options the sync reads (the public `apiKey` is never used). */
 export type TypesenseSyncConfig = Pick<
   TypesenseOptions,
-  "collection" | "host" | "port" | "protocol"
+  "collection" | "host" | "locale" | "port" | "protocol"
 >;
 
+type TypesenseClient = InstanceType<typeof TypesenseSdk.Client>;
+
+/**
+ * The collection an alias points at, or `undefined` when there is no such
+ * alias. Only a 404 means that: any other failure (a key that can't read
+ * aliases, an outage) throws before the sync has touched anything.
+ */
+const aliasTarget = async (
+  client: TypesenseClient,
+  alias: string,
+  errors: typeof TypesenseSdk.Errors
+): Promise<string | undefined> => {
+  try {
+    const { collection_name: target } = await client.aliases(alias).retrieve();
+    return target;
+  } catch (error) {
+    if (error instanceof errors.ObjectNotFound) {
+      return undefined;
+    }
+    throw error;
+  }
+};
+
 /**
- * Import the search records into a Typesense collection. Uses the admin key
- * from `TYPESENSE_ADMIN_API_KEY`. Throws on a missing key so the caller can
- * warn.
+ * Import the search records into Typesense. Uses the admin key from
+ * `TYPESENSE_ADMIN_API_KEY`. Throws on a missing key so the caller can warn.
  *
- * The collection is dropped and recreated on each sync so that pages deleted or
- * renamed since the last sync don't linger as stale search hits that 404 when
- * clicked (an upsert alone never removes them).
+ * `collection` names an alias. Each sync imports every record into a new
+ * collection (`<collection>_<timestamp>`), points the alias at it, then drops
+ * the collection it replaced: searches keep reading the previous collection
+ * until the new one is complete, pages deleted or renamed since the last sync
+ * don't linger as stale hits that 404 when clicked, and a sync that fails
+ * leaves the previous collection serving. A collection named `collection`
+ * itself, from a sync before the alias existed, is dropped just before the
+ * alias takes its name, since Typesense won't let the two share one.
  */
 export const syncTypesense = async (
   records: SearchRecord[],
@@ -29,7 +56,7 @@ export const syncTypesense = async (
   }
   // `require`, not `import()`: this runs in `astro:build:done` (see
   // `core/node-require.ts`).
-  const { Client }: typeof TypesenseSdk = nodeRequire("typesense");
+  const { Client, Errors }: typeof TypesenseSdk = nodeRequire("typesense");
   const client = new Client({
     apiKey: adminKey,
     nodes: [
@@ -41,23 +68,18 @@ export const syncTypesense = async (
     ],
   });
 
-  const collection = client.collections(config.collection);
-  let exists = true;
-  try {
-    await collection.retrieve();
-  } catch {
-    exists = false;
-  }
-  if (exists) {
-    await collection.delete();
-  }
+  const alias = config.collection;
+  const previous = await aliasTarget(client, alias, Errors);
+  const name = `${alias}_${Date.now()}`;
+  // The searched text fields, tokenized for `locale` when the site sets one.
+  const text = config.locale ? { locale: config.locale } : {};
   await client.collections().create({
     fields: [
-      { name: "title", type: "string" },
-      { name: "description", optional: true, type: "string" },
-      { name: "content", type: "string" },
+      { name: "title", type: "string", ...text },
+      { name: "description", optional: true, type: "string", ...text },
+      { name: "content", type: "string", ...text },
       { name: "url", type: "string" },
-      { name: "keywords", optional: true, type: "string[]" },
+      { name: "keywords", optional: true, type: "string[]", ...text },
       // The dialog sorts close matches by it (search.boost, 1 by default).
       { name: "boost", type: "float" },
       { facet: true, name: "tag", optional: true, type: "string" },
@@ -66,7 +88,7 @@ export const syncTypesense = async (
       { facet: true, name: "locale", optional: true, type: "string" },
       { facet: true, name: "version", optional: true, type: "string" },
     ],
-    name: config.collection,
+    name,
   });
 
   const documents = records.map((record) => ({
@@ -81,8 +103,31 @@ export const syncTypesense = async (
     url: record.url,
     version: record.version,
   }));
-  await client
-    .collections(config.collection)
-    .documents()
-    .import(documents, { action: "upsert" });
+  try {
+    await client
+      .collections(name)
+      .documents()
+      .import(documents, { action: "upsert" });
+  } catch (error) {
+    // Nothing reads the new collection yet: drop it, and the alias keeps
+    // serving the last complete sync.
+    await client.collections(name).delete();
+    throw error;
+  }
+
+  if (previous === undefined) {
+    let legacy = true;
+    try {
+      await client.collections(alias).retrieve();
+    } catch {
+      legacy = false;
+    }
+    if (legacy) {
+      await client.collections(alias).delete();
+    }
+  }
+  await client.aliases().upsert(alias, { collection_name: name });
+  if (previous !== undefined) {
+    await client.collections(previous).delete();
+  }
 };

package/src/seo/jsonld.ts

@@ -19,7 +19,7 @@ export interface PostalAddressIdentity {
 
 /**
  * `seo.organization`: the organization behind the site, emitted on every page
- * as an `Organization` node the WebSite and article nodes cite as publisher.
+ * as an `Organization` node the WebSite and page nodes cite as publisher.
  */
 export interface OrganizationIdentity {
   address?: PostalAddressIdentity;
@@ -73,6 +73,12 @@ export interface StructuredDataInput {
   description?: string;
   /** Page route, e.g. `/blog/post`. */
   route: string;
+  /**
+   * The route of this page's homepage: the navigation tree root
+   * (`navigation.root` — `/fr` for a locale, `/docs` under a `basePath`,
+   * `/v1.0` in an archived version). Defaults to `/`.
+   */
+  homeRoute?: string;
   /** Deployment base (`import.meta.env.BASE_URL`); prefixed onto absolute URLs. */
   base?: string;
   /** Content type — `blog` and `changelog` map to richer article types. */
@@ -246,24 +252,41 @@ const softwareNode = (
   return node;
 };
 
-/** The page as an article node (`BlogPosting`/`TechArticle`). */
-const articleNode = (
+/** The page's schema.org `@type`: a `WebPage` for a homepage, else an article. */
+const pageSchemaType = (input: StructuredDataInput, home: boolean): string => {
+  if (home) {
+    return "WebPage";
+  }
+  const pageType = input.pageType ?? "";
+  return isArticleType(pageType) ? ARTICLE_TYPES[pageType] : "TechArticle";
+};
+
+/**
+ * The page's own node: a homepage is a `WebPage` (it isn't an article, but it
+ * still needs a machine-readable date, or search engines take whatever other
+ * date the page shows), and every other page an article (`BlogPosting`/
+ * `TechArticle`) with a `headline`. Both carry the language, description,
+ * dates, the WebSite they belong to, and the publisher.
+ */
+const pageNode = (
   input: StructuredDataInput,
   context: {
     base: string | null;
+    home: boolean;
     organizationId: string | null;
     pageUrl: string;
   }
 ): JsonLdNode => {
-  const pageType = input.pageType ?? "";
   const node: JsonLdNode = {
     "@id": `${context.pageUrl}#page`,
-    "@type": isArticleType(pageType) ? ARTICLE_TYPES[pageType] : "TechArticle",
-    headline: input.title,
+    "@type": pageSchemaType(input, context.home),
     inLanguage: input.locale || "en",
     name: input.title,
     url: context.pageUrl,
   };
+  if (!context.home) {
+    node.headline = input.title;
+  }
   if (input.description) {
     node.description = input.description;
   }
@@ -315,14 +338,11 @@ const breadcrumbNode = (
 /**
  * Build a schema.org JSON-LD `@graph` for a page: site identity (the WebSite,
  * plus the configured Organization everywhere and the SoftwareApplication on
- * the homepage), the page as an article, and its breadcrumb trail. Returns
- * null when there is nothing useful to emit (e.g. the homepage without a
- * configured site). URLs are absolute when `siteUrl` is set, otherwise
- * route-relative.
+ * the homepage), the page itself (a WebPage on the homepage, an article
+ * elsewhere), and an article's breadcrumb trail. URLs are absolute when
+ * `siteUrl` is set, otherwise route-relative.
  */
-export const buildStructuredData = (
-  input: StructuredDataInput
-): JsonLdNode | null => {
+export const buildStructuredData = (input: StructuredDataInput): JsonLdNode => {
   const base = input.siteUrl ? trimSlash(input.siteUrl) : null;
   // Routes carry `basePath`; a `deployment.base` subdirectory is layered on top
   // so JSON-LD URLs match the served location.
@@ -365,9 +385,11 @@ export const buildStructuredData = (
     );
   }
 
-  // The homepage is described by the WebSite node (and the product, when one
-  // is configured); deeper pages get an article node plus a breadcrumb trail.
-  if (input.route === "/") {
+  // The homepage is a WebPage, next to the product when one is configured;
+  // deeper pages are articles with a breadcrumb trail.
+  const home = input.route === (input.homeRoute ?? "/");
+  graph.push(pageNode(input, { base, home, organizationId, pageUrl }));
+  if (home) {
     if (software && base) {
       graph.push(
         softwareNode(software, {
@@ -380,15 +402,11 @@ export const buildStructuredData = (
       );
     }
   } else {
-    graph.push(articleNode(input, { base, organizationId, pageUrl }));
     const breadcrumbs = breadcrumbNode(input.breadcrumbs, base, deployBase);
     if (breadcrumbs) {
       graph.push(breadcrumbs);
     }
   }
 
-  if (graph.length === 0) {
-    return null;
-  }
   return { "@context": "https://schema.org", "@graph": graph };
 };

package/src/sources/contentful.ts

@@ -21,10 +21,20 @@ export interface ContentfulOptions extends SharedSourceOptions {
    * / `sys.updatedAt`.
    */
   fields?: SourceFieldMap;
+  /**
+   * Delivery API host name. Defaults to `cdn.contentful.com`; a space with
+   * EU data residency reads from `cdn.eu.contentful.com`.
+   */
+  host?: string;
   /** Locale code to fetch; omit for the space's default locale. */
   locale?: string;
   /** Extra query parameters for the entries request (`"fields.section": "sdk"`). */
   params?: Record<string, string>;
+  /**
+   * Preview API host name for `--preview`. Defaults to
+   * `preview.contentful.com` (`preview.eu.contentful.com` in the EU).
+   */
+  previewHost?: string;
   /** Space id. */
   space: string;
 }
@@ -33,8 +43,10 @@ export const contentfulOptionsSchema = sharedSourceOptionsSchema.extend({
   contentType: z.string(),
   environment: z.string().optional(),
   fields: sourceFieldMapSchema.optional(),
+  host: z.string().optional(),
   locale: z.string().optional(),
   params: queryParamsSchema.optional(),
+  previewHost: z.string().optional(),
   space: z.string(),
 });
 

package/src/sources/github-releases.ts

@@ -7,7 +7,12 @@ import { sharedSourceOptionsSchema } from "./shared.ts";
 
 /** Options for {@link githubReleases}. */
 export interface GithubReleasesOptions extends SharedSourceOptions {
-  /** Include draft releases (needs a token with repo write access). */
+  /**
+   * The GitHub REST API base URL. Defaults to `https://api.github.com`; a
+   * GitHub Enterprise Server's is `https://<host>/api/v3`.
+   */
+  baseUrl?: string;
+  /** Include draft releases, tagged `Draft` (needs a token with repo write access). */
   drafts?: boolean;
   /** Cap the number of releases materialized, newest-first. Defaults to 100. */
   limit?: number;
@@ -20,6 +25,7 @@ export interface GithubReleasesOptions extends SharedSourceOptions {
 }
 
 export const githubReleasesOptionsSchema = sharedSourceOptionsSchema.extend({
+  baseUrl: z.string().optional(),
   drafts: z.boolean().optional(),
   limit: z.number().positive().optional(),
   owner: z.string(),

package/src/sources/notion.ts

@@ -11,6 +11,12 @@ export interface NotionOptions extends SharedSourceOptions {
   concurrency?: number;
   /** Notion database id. */
   database: string;
+  /**
+   * Read text typed in Notion as MDX, so components and Markdown in it
+   * render. Anyone who can edit the database can then run code at build
+   * time. Default false: text renders as written.
+   */
+  mdx?: boolean;
   /** Notion property names mapped onto Blume meta. */
   properties?: {
     /** Property holding the page description. */
@@ -31,6 +37,7 @@ export interface NotionOptions extends SharedSourceOptions {
 export const notionOptionsSchema = sharedSourceOptionsSchema.extend({
   concurrency: z.number().positive().optional(),
   database: z.string(),
+  mdx: z.boolean().optional(),
   properties: z
     .strictObject({
       description: z.string().optional(),

package/src/sources/shared.ts

@@ -33,6 +33,8 @@ export interface SourceFieldMap {
   description?: string;
   /** Field holding the last-modified date. */
   lastModified?: string;
+  /** Field holding the sidebar order (a number). No default: unset, none is read. */
+  order?: string;
   /** Field holding the page slug. */
   slug?: string;
   /** Field holding the page title. */
@@ -44,6 +46,7 @@ export const sourceFieldMapSchema = z.strictObject({
   body: z.string().optional(),
   description: z.string().optional(),
   lastModified: z.string().optional(),
+  order: z.string().optional(),
   slug: z.string().optional(),
   title: z.string().optional(),
 });

package/src/theme/color.ts

@@ -374,16 +374,15 @@ const rectangular = (lightness: number, chroma: number, hue: number) => {
 /** A color function's channels, converted to sRGB with `alpha`. */
 type Converter = (channels: Channels, alpha: number) => Rgba;
 
-const rgb: Converter = ([red, green, blue], alpha) => {
-  const channel = (component: Component): number =>
-    clamp(scaled(component, 255) / 255);
-  return {
-    alpha,
-    blue: channel(blue),
-    green: channel(green),
-    red: channel(red),
-  };
-};
+const rgbChannel = (component: Component): number =>
+  clamp(scaled(component, 255) / 255);
+
+const rgb: Converter = ([red, green, blue], alpha) => ({
+  alpha,
+  blue: rgbChannel(blue),
+  green: rgbChannel(green),
+  red: rgbChannel(red),
+});
 
 /** A converter for a hue-and-two-percentages function (`hsl()`, `hwb()`). */
 const cylindrical =

package/src/theme/entry.ts

@@ -263,13 +263,24 @@ ${THEME_MAPPING}
    so a large site's HTML is mostly this markup — one utility per row kind
    instead of the dozen classes each expands to keeps every page (and the
    build's HTML output) small. Kept in sync with NavTree.astro: a page row,
-   a page-mode group's drill-in button, a collapsible group's summary and
-   the link inside it, and a flat group's heading and the link inside it. */
+   a page-mode group's drill-in row (or, when the group has a page, the
+   link and chevron button it splits into), a collapsible group's summary
+   and the link inside it, and a flat group's heading and the link inside
+   it. */
 @utility blume-nav-link {
   @apply block rounded-[0.65rem] px-2.5 py-1.5 text-muted-foreground text-sm transition-colors hover:bg-muted hover:text-foreground aria-[current=page]:bg-muted aria-[current=page]:font-medium aria-[current=page]:text-foreground;
 }
 @utility blume-nav-drill {
-  @apply flex w-full items-center gap-2 rounded-[0.65rem] px-2.5 py-1.5 text-start font-medium text-foreground text-sm transition-colors hover:bg-muted;
+  @apply flex w-full items-center gap-2 rounded-[0.65rem] px-2.5 py-1.5 text-start font-medium text-foreground text-sm transition-colors hover:bg-muted aria-[current]:bg-muted;
+}
+/* A routed drill row's label and chevron are separate pills, like a panel's
+   back button and title, so each shows which one the pointer is on. The
+   chevron's padding matches the drill row's, so chevrons line up. */
+@utility blume-nav-drill-link {
+  @apply flex min-w-0 flex-1 items-center gap-2 rounded-[0.65rem] px-2.5 py-1.5 font-medium text-foreground text-sm transition-colors hover:bg-muted aria-[current]:bg-muted;
+}
+@utility blume-nav-drill-toggle {
+  @apply flex shrink-0 items-center justify-center self-stretch rounded-[0.65rem] px-2.5 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground;
 }
 @utility blume-nav-summary {
   @apply flex cursor-pointer list-none items-center gap-1.5 rounded-[0.65rem] px-2.5 py-1.5 text-muted-foreground text-sm transition-colors hover:bg-muted hover:text-foreground [&::-webkit-details-marker]:hidden;
@@ -940,8 +951,11 @@ pre:has(.line.focused):hover .line:not(.focused) {
    Strip the surrounding chrome so the printout is just the article. Scoped to
    the chrome itself, never bare \`header\`/\`aside\`: content renders those too
    (every Callout and Panel is an <aside>, every changelog Update has a
-   <header>), and they belong in the printout. \`body > header\` keeps a
-   \`layout.Header\` override out as well. */
+   <header>), and they belong in the printout. \`body > header\` and
+   \`body > footer\` keep \`layout.Header\` and \`layout.Footer\` overrides out
+   as well. Everything after the article (directory and related-page cards,
+   last updated, feedback, prev/next) is page chrome too, and so are the
+   copy, ask, and expand buttons on code blocks. */
 @media print {
   [data-blume-banner],
   [data-blume-header],
@@ -951,7 +965,13 @@ pre:has(.line.focused):hover .line:not(.focused) {
   [data-blume-assistant-panel],
   [data-blume-page-actions],
   #blume-content > nav,
-  #blume-content > details {
+  #blume-content > details,
+  [data-blume-page-end],
+  [data-blume-footer],
+  body > footer,
+  [data-blume-copy],
+  [data-blume-ask],
+  [data-blume-code-expand] {
     display: none !important;
   }
 
@@ -962,6 +982,23 @@ pre:has(.line.focused):hover .line:not(.focused) {
     overflow: visible;
   }
 
+  /* A collapsed \`expandable\` block prints open: its toggle is hidden above,
+     so the collapse would cut the block off at its first lines. Same
+     selector as the collapse, so this later rule wins. */
+  .prose pre[data-expandable]:not([data-expanded]) > code {
+    mask-image: none;
+    max-height: none;
+    overflow-y: visible;
+  }
+
+  /* The theme script switches a dark page to light for printing
+     (\`beforeprint\`); a color transition would print mid-fade. */
+  *,
+  *::before,
+  *::after {
+    transition: none !important;
+  }
+
   #blume-content {
     padding: 0 !important;
   }

package/src/translate/validate.ts

@@ -7,7 +7,8 @@ import { TRANSLATABLE_KEY_PATHS } from "./prompts.ts";
  * structure: the final frontmatter is *reconstructed* from the source (clone
  * the source data, overlay only the translatable string values), so invented
  * keys are dropped, deleted keys are restored, and slugs/icons/orders/dates
- * stay source-verbatim by construction. Only then is the file written.
+ * stay source-verbatim by construction. The one source key left out is
+ * `seo.canonical` (see `dropCanonical`). Only then is the file written.
  */
 
 export type ValidationResult =
@@ -93,6 +94,26 @@ const setPath = (
   parent[path.at(-1) as string] = value;
 };
 
+/**
+ * Drop `seo.canonical`, and `seo` with it when nothing else is left. The
+ * source's canonical names a page in the source language (most often the
+ * source page itself); copied into a translation, it would canonicalize the
+ * translation to another language and take it out of search. Without it the
+ * translation gets Blume's default canonical: its own URL.
+ */
+const dropCanonical = (data: FrontmatterData): void => {
+  const { seo } = data;
+  if (!isKeyedObject(seo) || !("canonical" in seo)) {
+    return;
+  }
+  const { canonical: _canonical, ...rest } = seo;
+  if (Object.keys(rest).length > 0) {
+    data.seo = rest;
+  } else {
+    delete data.seo;
+  }
+};
+
 const ensureTrailingNewline = (text: string): string =>
   text.endsWith("\n") ? text : `${text}\n`;
 
@@ -181,6 +202,7 @@ export const validateTranslation = (
       setPath(data, path, translated);
     }
   }
+  dropCanonical(data);
 
   return {
     ok: true,