blume 2.0.3 → 2.1.0

package/src/core/i18n-ui.ts

@@ -15,6 +15,8 @@ const uiStringsObject = z.object({
     .object({
       addToCursor: z.string().default("Add to Cursor"),
       addToVscode: z.string().default("Add to VS Code"),
+      // A code block's button that opens the assistant with the code attached.
+      askAboutCode: z.string().default("Ask about this code"),
       connectMcp: z.string().default("Connect to MCP"),
       copied: z.string().default("Copied!"),
       copyClaudeCode: z.string().default("Copy Claude Code command"),
@@ -47,11 +49,32 @@ const uiStringsObject = z.object({
       copy: z.string().default("Copy conversation"),
       empty: z.string().default("Ask a question about the docs."),
       error: z.string().default("Sorry, something went wrong."),
+      // The question sent about an attached code block when the reader
+      // writes none.
+      explainCode: z.string().default("Explain this code."),
       label: z.string().default("Ask a question"),
+      // The header trigger's tooltip.
+      open: z.string().default("Open assistant"),
       placeholder: z.string().default("Ask a question…"),
+      // The answer when the rate limit (`rateLimit`) turns a question away.
+      rateLimited: z
+        .string()
+        .default(
+          "You've asked a lot of questions. Try again in a few minutes."
+        ),
+      // The attached code block's dismiss button.
+      removeCode: z.string().default("Remove code"),
       send: z.string().default("Send"),
+      // The link to your support channel (`ai.assistant.support`), and the
+      // subject of an email it starts.
+      support: z.string().default("Contact support"),
+      supportSubject: z.string().default("Question from the docs"),
       tip: z.string().default("Tip: You can open and close chat with"),
       title: z.string().default("Assistant"),
+      // The answer when the bot check (`ai.assistant.captcha`) fails.
+      verifyFailed: z
+        .string()
+        .default("We couldn't check that you're human. Try again."),
       you: z.string().default("You"),
     })
     .prefault({}),
@@ -70,6 +93,23 @@ const uiStringsObject = z.object({
       title: z.string().default("Changelog"),
     })
     .prefault({}),
+  // The built-in cookie consent banner (`consent: native()`) and the footer
+  // link that reopens a consent manager's preferences.
+  consent: z
+    .object({
+      accept: z.string().default("Accept"),
+      decline: z.string().default("Decline"),
+      // The banner's accessible name.
+      label: z.string().default("Cookie consent"),
+      message: z
+        .string()
+        .default(
+          "We'd like to use cookies to understand how these docs are used."
+        ),
+      policy: z.string().default("Privacy policy"),
+      settings: z.string().default("Cookie settings"),
+    })
+    .prefault({}),
   content: z
     .object({
       // `<Component>`'s source tab.
@@ -89,7 +129,12 @@ const uiStringsObject = z.object({
       prop: z.string().default("Prop"),
       // `<Tabs dropdown>`: the accessible name of the tab picker.
       selectTab: z.string().default("Select tab"),
-      // `<Expandable>`'s toggle when it sets no `title`.
+      // `<View>`: the accessible name of the page's view picker.
+      selectView: z.string().default("Select view"),
+      // An expanded `expandable` code block's toggle.
+      showLess: z.string().default("Show less"),
+      // `<Expandable>`'s toggle when it sets no `title`, and a collapsed
+      // `expandable` code block's.
       showMore: z.string().default("Show more"),
       stars: z.string().default("Stars"),
       // An untitled tab's label; `{n}` is replaced with its position.
@@ -102,8 +147,11 @@ const uiStringsObject = z.object({
     .prefault({}),
   feedback: z
     .object({
+      // The written comment box after the rating (`feedback.comments`).
+      comment: z.string().default("Tell us more (optional)"),
       no: z.string().default("No"),
       question: z.string().default("Was this page helpful?"),
+      send: z.string().default("Send"),
       thanks: z.string().default("Thanks for your feedback!"),
       yes: z.string().default("Yes"),
     })
@@ -114,6 +162,36 @@ const uiStringsObject = z.object({
       untranslated: z.string().default("Not translated"),
     })
     .prefault({}),
+  narration: z
+    .object({
+      // Spoken, not shown: the cues that introduce a callout of each type, a
+      // step (`{n}` is its number), a tab (`{title}` is its label), and a
+      // collapsible section. End each with a full stop so it reads as its own
+      // sentence.
+      cueDanger: z.string().default("Danger."),
+      cueInfo: z.string().default("Info."),
+      cueNote: z.string().default("Note."),
+      cueSection: z.string().default("Expandable section."),
+      cueStep: z.string().default("Step {n}."),
+      cueSuccess: z.string().default("Success."),
+      cueTab: z.string().default("{title} tab."),
+      cueTip: z.string().default("Tip."),
+      cueWarning: z.string().default("Warning."),
+      error: z.string().default("The narration couldn't load."),
+      // Resumes following the sentence being read after the reader scrolls away.
+      follow: z.string().default("Follow along"),
+      label: z.string().default("Listen to this page"),
+      // The estimated listening time; `{n}` is whole minutes.
+      minutes: z.string().default("{n} min"),
+      next: z.string().default("Next sentence"),
+      pause: z.string().default("Pause"),
+      play: z.string().default("Play"),
+      previous: z.string().default("Previous sentence"),
+      progress: z.string().default("Narration progress"),
+      speed: z.string().default("Playback speed"),
+      stop: z.string().default("Stop listening"),
+    })
+    .prefault({}),
   nav: z
     .object({
       back: z.string().default("Back"),
@@ -128,7 +206,7 @@ const uiStringsObject = z.object({
       primary: z.string().default("Primary"),
       sections: z.string().default("Sections"),
       toggleNavigation: z.string().default("Toggle navigation"),
-      toggleTheme: z.string().default("Toggle color theme"),
+      toggleTheme: z.string().default("Toggle theme"),
     })
     .prefault({}),
   notFound: z
@@ -154,6 +232,8 @@ const uiStringsObject = z.object({
       next: z.string().default("Next"),
       pagination: z.string().default("Pagination"),
       previous: z.string().default("Previous"),
+      // The heading over a page's `related` links.
+      related: z.string().default("Related pages"),
       skipToContent: z.string().default("Skip to content"),
     })
     .prefault({}),

package/src/core/includes.ts

@@ -7,6 +7,7 @@ import type { FenceState } from "./code-fences.ts";
 import matter from "./frontmatter.ts";
 import { INLINE_CODE, MD_IMAGE, targetOffsetIn } from "./sources/normalize.ts";
 import type { Diagnostic } from "./types.ts";
+import { substituteVariables } from "./variables.ts";
 
 /**
  * Content includes: `<include>./relative.mdx</include>` on a line of its own
@@ -98,6 +99,12 @@ export interface IncludeAttributes {
   lang?: string;
   /** Fence meta string in code-block mode (e.g. `title="lib.ts"`). */
   meta?: string;
+  /**
+   * Every other attribute with a value: the snippet's own variables.
+   * `<include plan="Pro">` makes `{{plan}}` in the included file read `Pro`,
+   * ahead of any site-wide variable of the same name.
+   */
+  props?: Record<string, string>;
 }
 
 /** A parsed include statement. */
@@ -108,8 +115,8 @@ export interface IncludeStatement {
 
 /**
  * Parse one trimmed line as an include statement, or `null` when it isn't
- * one. Only `lang` and `meta` are meaningful; unknown attributes parse and
- * are ignored so a future attribute degrades gracefully on older versions.
+ * one. `lang` and `meta` shape a code include; every other attribute with a
+ * value becomes a prop, a variable scoped to the included file.
  */
 export const parseIncludeStatement = (
   line: string
@@ -128,6 +135,9 @@ export const parseIncludeStatement = (
     if (name === "meta" && value) {
       attributes.meta = value;
     }
+    if (name && name !== "lang" && name !== "meta" && value !== undefined) {
+      attributes.props = { ...attributes.props, [name]: value };
+    }
   }
   return { attributes, target: match.groups.target ?? "" };
 };
@@ -519,8 +529,15 @@ const expandStatement = async (
     lines.shift();
     origins.shift();
   }
+  // Props replace their `{{name}}` references line by line, so every line
+  // keeps its origin; they reach the file's own nested includes too.
+  const { props } = statement.attributes;
   return {
-    lines: rebaseImages(lines, dirname(path), dirname(filePath)),
+    lines: rebaseImages(
+      props ? lines.map((text) => substituteVariables(text, props)) : lines,
+      dirname(path),
+      dirname(filePath)
+    ),
     origins,
   };
 };

package/src/core/links.ts

@@ -10,6 +10,7 @@ import {
 import type { LocaleRouting } from "./i18n.ts";
 import { localizeLinkPath } from "./locale-links.ts";
 import { gradeExternal, probeAll } from "./probe.ts";
+import { isPatternPath, pathsUnderPattern } from "./redirect-patterns.ts";
 import type {
   ContentGraph,
   Diagnostic,
@@ -87,6 +88,8 @@ interface LinkContext {
   publicDir: string | null;
   /** Normalized `redirect.from` paths — valid targets that resolve at runtime. */
   redirects: Set<string>;
+  /** Pattern `redirect.from`s (`/beta/:slug*`), based like `redirects`. */
+  redirectPatterns: string[];
   routes: Set<string>;
 }
 
@@ -322,10 +325,16 @@ const checkPathLink = (
   if (ctx.extraRoutes.has(route)) {
     return null;
   }
-  // A configured `redirect.from` resolves at runtime, so it's a valid target.
+  // A configured `redirect.from`, or a path a pattern `from` covers, resolves
+  // at runtime, so it's a valid target.
   // Its destination (and any anchor there) is validated on its own page, so we
   // don't follow the redirect to check the fragment here.
-  if (ctx.redirects.has(route)) {
+  if (
+    ctx.redirects.has(route) ||
+    ctx.redirectPatterns.some(
+      (from) => pathsUnderPattern(from, [route]).length > 0
+    )
+  ) {
     return null;
   }
 
@@ -585,6 +594,11 @@ export const validateLinks = async (
     fileRoutes: buildFileRouteIndex(graph.pages, options.i18n ?? null),
     i18n: options.i18n ?? null,
     publicDir: options.publicDir,
+    redirectPatterns: (options.redirects ?? []).flatMap((redirect) =>
+      isPatternPath(redirect.from)
+        ? [withBasePath(basePath, redirect.from)]
+        : []
+    ),
     redirects: new Set(
       (options.redirects ?? []).map((redirect) =>
         toRoute(withBasePath(basePath, redirect.from))

package/src/core/localizable.ts

@@ -0,0 +1,26 @@
+import type { LocalizableLabel } from "./schema.ts";
+
+/** A label is either one string for every locale or a per-locale map. */
+const isSingleLabel = (label: LocalizableLabel): label is string =>
+  typeof label === "string";
+
+/**
+ * Resolve a possibly-per-locale label to the string a locale renders: the
+ * active locale's entry, else the default locale's, else the map's first
+ * entry (which is also what a single-locale site gets).
+ */
+export const resolveLocalizable = (
+  label: LocalizableLabel,
+  locale?: string,
+  defaultLocale?: string
+): string => {
+  if (isSingleLabel(label)) {
+    return label;
+  }
+  return (
+    (locale === undefined ? undefined : label[locale]) ??
+    (defaultLocale === undefined ? undefined : label[defaultLocale]) ??
+    Object.values(label)[0] ??
+    ""
+  );
+};

package/src/core/navigation.ts

@@ -3,6 +3,7 @@ import { extname } from "pathe";
 import { stripBasePath, withBasePath } from "./base-path.ts";
 import { orderingPrefix, stripOrderingPrefix } from "./ordering-prefix.ts";
 import type {
+  DirectoryMode,
   FolderMeta,
   SidebarDisplay,
   SidebarItemConfig,
@@ -202,6 +203,7 @@ interface MutableGroup {
   label: string;
   icon?: string;
   collapsed?: boolean;
+  directory?: DirectoryMode;
   display?: SidebarDisplay;
   order: number;
   /** Whether `order` is the node's position in its folder meta `pages` list. */
@@ -305,9 +307,19 @@ interface FallbackFolderMeta {
   meta: (path: string) => FolderMeta | undefined;
 }
 
+/** A folder meta's own fields onto its group, over what the folder implied. */
+const applyMetaFields = (group: MutableGroup, meta: FolderMeta): void => {
+  group.label = meta.title ?? group.label;
+  group.icon = meta.icon ?? group.icon;
+  group.order = meta.order ?? group.order;
+  group.collapsed = meta.collapsed ?? group.collapsed;
+  group.directory = meta.directory ?? group.directory;
+};
+
 /**
- * Apply folder meta (title/order/icon/collapsed/display and explicit page
- * order), plus the index-frontmatter display sugar collected per folder path.
+ * Apply folder meta (title/order/icon/collapsed/display/directory and
+ * explicit page order), plus the index-frontmatter display sugar collected
+ * per folder path.
  */
 const applyFolderMeta = (
   group: MutableGroup,
@@ -346,10 +358,7 @@ const applyFolderMeta = (
     (mirrored ? fallback.indexDisplay.get(group.path) : undefined) ??
     meta?.display;
   if (meta) {
-    group.label = meta.title ?? group.label;
-    group.icon = meta.icon ?? group.icon;
-    group.order = meta.order ?? group.order;
-    group.collapsed = meta.collapsed ?? group.collapsed;
+    applyMetaFields(group, meta);
   }
 
   for (const child of group.children) {
@@ -630,7 +639,15 @@ const hoistTabSections = (
   }
 };
 
-const toNavNode = (node: MutableNode, display: SidebarDisplay): NavNode => {
+/**
+ * A group's directory mode: its own, else the nearest one set above it (see
+ * `directory` in `schema.ts`).
+ */
+const toNavNode = (
+  node: MutableNode,
+  display: SidebarDisplay,
+  inheritedDirectory?: DirectoryMode
+): NavNode => {
   if (node.kind === "page") {
     return {
       badge: node.badge,
@@ -643,9 +660,13 @@ const toNavNode = (node: MutableNode, display: SidebarDisplay): NavNode => {
       route: node.route,
     };
   }
+  const directory = node.directory ?? inheritedDirectory;
   return {
-    children: node.children.map((child) => toNavNode(child, display)),
+    children: node.children.map((child) =>
+      toNavNode(child, display, directory)
+    ),
     collapsed: node.collapsed,
+    directory,
     display: node.display ?? display,
     icon: node.icon,
     kind: "group",
@@ -805,7 +826,9 @@ const buildFileSystemSidebar = (
   sortNodes(root.children, diagnostics);
   hoistPages(root.children, display, true);
   hoistTabSections(root.children, tabPaths, display);
-  return root.children.map((child) => toNavNode(child, display));
+  return root.children.map((child) =>
+    toNavNode(child, display, root.directory)
+  );
 };
 
 /**
@@ -932,16 +955,24 @@ const buildConfigSidebar = (
   items: SidebarItemConfig[],
   byRoute: Map<string, PageRecord>,
   display: SidebarDisplay,
-  basePath: string
+  basePath: string,
+  inheritedDirectory?: DirectoryMode
 ): NavNode[] => {
   const nodes: NavNode[] = [];
   for (const item of items) {
     if (!isPageRef(item) && item.items) {
+      const directory = item.directory ?? inheritedDirectory;
       nodes.push({
         badge: item.badge,
-        children: buildConfigSidebar(item.items, byRoute, display, basePath),
+        children: buildConfigSidebar(
+          item.items,
+          byRoute,
+          display,
+          basePath,
+          directory
+        ),
         collapsed: item.collapsed,
-        directory: item.directory,
+        directory,
         display: item.display ?? display,
         icon: item.icon,
         kind: "group",

package/src/core/page-modes.ts

@@ -0,0 +1,56 @@
+/**
+ * Page layout modes (`mode` frontmatter), Mintlify's names for what a page
+ * shows around its content:
+ *
+ * - `default`: the sidebar, the page's title and table of contents, and the
+ *   page-end links, around the prose column.
+ * - `wide`: no table of contents; the content takes its width.
+ * - `center`: no sidebar or table of contents; a wider column, centered.
+ *   For changelogs and other pages read top to bottom.
+ * - `custom`: only the header. No sidebar, title, breadcrumbs, table of
+ *   contents, page-end links, or site footer, and the content spans the
+ *   page, for a landing page written in MDX.
+ * - `frame`: `custom`, keeping the sidebar.
+ *
+ * Mintlify's `assistant` mode, a full-page chat, has no equivalent.
+ */
+export const PAGE_MODES = [
+  "default",
+  "wide",
+  "center",
+  "custom",
+  "frame",
+] as const;
+
+export type PageMode = (typeof PAGE_MODES)[number];
+
+/** What a page shows around its content, and how wide the content runs. */
+export interface PageModeLayout {
+  /** The page's own chrome: title, description, breadcrumbs, page-end links, and the site footer. */
+  chrome: boolean;
+  sidebar: boolean;
+  toc: boolean;
+  /** `content` is the prose measure, `center` a wider centered column, `full` the whole column. */
+  width: "content" | "center" | "full";
+}
+
+/** The layout a mode gives a page. */
+export const pageModeLayout = (mode: PageMode = "default"): PageModeLayout => {
+  switch (mode) {
+    case "wide": {
+      return { chrome: true, sidebar: true, toc: false, width: "full" };
+    }
+    case "center": {
+      return { chrome: true, sidebar: false, toc: false, width: "center" };
+    }
+    case "custom": {
+      return { chrome: false, sidebar: false, toc: false, width: "full" };
+    }
+    case "frame": {
+      return { chrome: false, sidebar: true, toc: false, width: "full" };
+    }
+    default: {
+      return { chrome: true, sidebar: true, toc: true, width: "content" };
+    }
+  }
+};

package/src/core/project-graph.ts

@@ -1,5 +1,6 @@
 import { isAbsolute, relative } from "pathe";
 
+import { withBasePath } from "./base-path.ts";
 import { CHANGELOG_INDEX_ROUTE, hasChangelogIndex } from "./changelog-index.ts";
 import { loadConfig } from "./config.ts";
 import { customStaticRoutes, discoverPages } from "./custom-pages.ts";
@@ -18,10 +19,15 @@ import { buildManifest } from "./manifest.ts";
 import { discoverFolderMeta } from "./meta.ts";
 import type { FolderMetaSource } from "./meta.ts";
 import { resolveProjectContext } from "./project.ts";
+import { pathsUnderPattern } from "./redirect-patterns.ts";
 import type { ResolvedConfig } from "./schema.ts";
 import { normalizeEntry, strippedLineOffset } from "./sources/normalize.ts";
 import { resolveDocsCollection, resolveSources } from "./sources/resolve.ts";
-import type { ContentSource, SourceLoadResult } from "./sources/types.ts";
+import type {
+  ContentSource,
+  SourceEntry,
+  SourceLoadResult,
+} from "./sources/types.ts";
 import type {
   BlumeManifest,
   ContentGraph,
@@ -30,6 +36,12 @@ import type {
   PageRecord,
   ProjectContext,
 } from "./types.ts";
+import {
+  hasVariables,
+  substituteVariables,
+  undefinedVariables,
+} from "./variables.ts";
+import type { ContentVariables } from "./variables.ts";
 import { versionsDiagnostics } from "./versions.ts";
 
 /** Build mode: drafts are kept in `dev` and dropped in `build`. */
@@ -246,6 +258,85 @@ const isBannerShorthand = (
   banner: NonNullable<ResolvedConfig["banner"]>
 ): banner is string => typeof banner === "string";
 
+/**
+ * Report an entry's undefined content variables at their source lines, then
+ * replace the defined ones in the text the scan extracts from: the expanded
+ * text when includes were spliced (its `origins` map lines back to the file
+ * each came from), else the body.
+ */
+const substituteEntryVariables = (
+  entry: SourceEntry,
+  variables: ContentVariables
+): Diagnostic[] => {
+  const { expanded } = entry;
+  const text = expanded?.text ?? entry.body.text;
+  const offset = expanded ? 0 : strippedLineOffset(entry.raw, entry.body.text);
+  const diagnostics = undefinedVariables(text, variables).map(
+    ({ line, name }): Diagnostic => {
+      const origin = expanded?.origins[line - 1];
+      return {
+        code: "BLUME_UNDEFINED_VARIABLE",
+        file: origin?.file ?? entry.sourcePath,
+        line: origin?.line ?? line + offset,
+        message: `{{${name}}} isn't a defined variable, so it would show as written.`,
+        severity: "error",
+        suggestion: `Define "${name}" under variables in blume.config.ts, or put it in inline code to show it as written.`,
+      };
+    }
+  );
+  if (expanded) {
+    expanded.text = substituteVariables(expanded.text, variables);
+  } else {
+    entry.body.text = substituteVariables(entry.body.text, variables);
+  }
+  return diagnostics;
+};
+
+/** {@link substituteEntryVariables} over every loaded entry, when any are defined. */
+const substituteLoadedVariables = (
+  loaded: readonly SourceLoadResult[],
+  variables: ContentVariables
+): Diagnostic[] =>
+  hasVariables(variables)
+    ? loaded.flatMap(({ entries }) =>
+        entries.flatMap((entry) => substituteEntryVariables(entry, variables))
+      )
+    : [];
+
+/**
+ * A pattern redirect that also matches a page. Hosts disagree on which
+ * answers (Vercel and Cloudflare apply the rule ahead of the page, Netlify
+ * and the Node server serve the page), so the pattern is rejected rather than
+ * let the answer depend on the host. `pages` are the served page paths, which
+ * carry `basePath`, as the based `from` does.
+ */
+const redirectPageDiagnostics = (
+  config: ResolvedConfig,
+  pages: readonly string[],
+  configFile: string | null
+): Diagnostic[] =>
+  config.redirects.flatMap((redirect) => {
+    const matched = pathsUnderPattern(
+      withBasePath(config.basePath, redirect.from),
+      pages
+    );
+    const [first] = matched;
+    if (first === undefined) {
+      return [];
+    }
+    const more = matched.length > 1 ? ` and ${matched.length - 1} more` : "";
+    return [
+      {
+        code: "BLUME_REDIRECT_MATCHES_PAGE",
+        file: configFile ?? undefined,
+        message: `The redirect from ${redirect.from} also matches the page ${first}${more}, which some hosts would redirect and others would serve.`,
+        severity: "error",
+        suggestion:
+          "Narrow the pattern to the paths that moved, or move the pages out from under it.",
+      } satisfies Diagnostic,
+    ];
+  });
+
 /** The configured banner link target, when the banner has a link. */
 const bannerLinkHref = (
   banner: ResolvedConfig["banner"]
@@ -352,6 +443,14 @@ export const scanProject = async (
     })
   );
 
+  // Content variables: an undefined name in prose is an error at its source
+  // line, and every defined one is replaced in the text headings, links, and
+  // components are extracted from, so they match the rendered page.
+  const variableDiagnostics = substituteLoadedVariables(
+    loaded,
+    config.variables
+  );
+
   // Folder meta contributed by the sources themselves (the OpenAPI source
   // labels each tag directory with the spec's own tag name). It applies to
   // every locale, so it merges into the shared map — beneath user-authored
@@ -424,14 +523,15 @@ export const scanProject = async (
   const customPages = context.pagesRoot
     ? await discoverPages(context.pagesRoot)
     : [];
+  const extraRoutes = new Set([
+    ...customStaticRoutes(customPages),
+    ...(hasChangelogIndex(pages, config) ? [CHANGELOG_INDEX_ROUTE] : []),
+  ]);
   const graph = buildContentGraph(pages, {
     bannerHref: bannerLinkHref(config.banner),
     basePath: config.basePath,
     brandHref: logoHref(config.logo),
-    extraRoutes: new Set([
-      ...customStaticRoutes(customPages),
-      ...(hasChangelogIndex(pages, config) ? [CHANGELOG_INDEX_ROUTE] : []),
-    ]),
+    extraRoutes,
     folderMeta: folderMeta.meta,
     i18n: config.i18n,
     navigation: config.navigation,
@@ -453,6 +553,7 @@ export const scanProject = async (
     diagnostics: [
       ...contentDiagnostics,
       ...includeDiagnostics,
+      ...variableDiagnostics,
       ...folderMeta.diagnostics,
       ...entryIdDiagnostics(
         pages,
@@ -462,6 +563,11 @@ export const scanProject = async (
       ...i18nWarnings,
       ...versionWarnings,
       ...lastModifiedWarnings,
+      ...redirectPageDiagnostics(
+        config,
+        [...manifest.routes.map((route) => route.path), ...extraRoutes],
+        context.configFile
+      ),
     ],
     droppedPages,
     graph,