blume 2.0.2 → 2.0.3

package/src/core/diagnostics.ts

@@ -69,8 +69,10 @@ const DOCS_PATHS = new Map(
     BLUME_TRANSLATE_MISSING: "/docs/cli/translate",
     BLUME_TRANSLATE_STALE: "/docs/cli/translate",
     BLUME_UNKNOWN_COMPONENT: "/docs/configuration/customization",
+    BLUME_UNKNOWN_DIRECTIVE: "/docs/content/syntax",
     BLUME_UNKNOWN_ICON: DOCS_CONTENT_NAVIGATION,
     BLUME_UNKNOWN_OPTION: "/docs/cli",
+    BLUME_UNLOADABLE_FILE_NAME: "/docs/content",
     BLUME_WIKILINK_AMBIGUOUS: DOCS_CONTENT_SOURCES,
     BLUME_WIKILINK_UNRESOLVED: DOCS_CONTENT_SOURCES,
     BLUME_YARN_PNP: "/docs/quickstart",

package/src/core/directive-diagnostics.ts

@@ -0,0 +1,99 @@
+import type { Nodes } from "mdast";
+import { mdxToMdast } from "satteri";
+
+import {
+  CALLOUT_ALIASES,
+  CALLOUT_TYPES,
+  calloutTypeFor,
+} from "../markdown/directives.ts";
+import { MDX_BODY_FEATURES } from "../markdown/features.ts";
+import { strippedLineOffset } from "./sources/normalize.ts";
+import type { SourceEntry } from "./sources/types.ts";
+import type { Diagnostic } from "./types.ts";
+
+// A line that may open a container directive: a colon fence and a name, after
+// any quote or list indentation. A page is parsed only when one of these
+// names something other than a callout, so pages without one cost a scan.
+const CONTAINER_OPENING = /^[\t >]*:{3,}(?<name>[a-z][\w-]*)/gimu;
+
+const codeList = (names: Iterable<string>): string =>
+  [...names].map((name) => `\`${name}\``).join(", ");
+
+const CALLOUT_NAMES = `${codeList(CALLOUT_TYPES)} (or the aliases ${codeList(Object.keys(CALLOUT_ALIASES))})`;
+
+/** A container directive that isn't a callout, and its line in `text`. */
+interface UnknownContainer {
+  line: number;
+  name: string;
+}
+
+/**
+ * Every container directive in an `.mdx` body whose name isn't a callout, in
+ * source order. The body is parsed as the renderer reads it, so a fence in a
+ * code block or a `::: name` that isn't a directive at all never counts. A
+ * body MDX can't parse fails to render anyway, with its own error.
+ */
+const unknownContainers = (text: string): UnknownContainer[] => {
+  const named = [...text.matchAll(CONTAINER_OPENING)].some(
+    (match) => calloutTypeFor(match.groups?.name ?? "") === null
+  );
+  if (!named) {
+    return [];
+  }
+  let tree: Nodes;
+  try {
+    tree = mdxToMdast(text, { features: MDX_BODY_FEATURES });
+  } catch {
+    return [];
+  }
+  const found: UnknownContainer[] = [];
+  const walk = (node: Nodes): void => {
+    if (
+      node.type === "containerDirective" &&
+      calloutTypeFor(node.name) === null
+    ) {
+      found.push({ line: node.position?.start.line ?? 1, name: node.name });
+    }
+    if ("children" in node) {
+      for (const child of node.children) {
+        walk(child);
+      }
+    }
+  };
+  walk(tree);
+  return found;
+};
+
+/**
+ * Warn about each `:::name` container in an `.mdx` entry that isn't a callout.
+ * The page keeps its content — the body renders between the literal `:::`
+ * lines (see `markdown/directives.ts`) — but a typo like `:::warnig`, or a
+ * `:::details` carried over from another docs tool, should read as the
+ * mistake it is rather than as a finished page. Lines point into the file
+ * the author wrote, a partial's own file for a container an `<include>`
+ * brought in.
+ */
+export const unknownDirectiveDiagnostics = (
+  entry: SourceEntry,
+  sourceName: string
+): Diagnostic[] => {
+  if (entry.body.format !== "mdx") {
+    return [];
+  }
+  const page = entry.sourcePath ?? `${sourceName}:${entry.ref}`;
+  const offset =
+    entry.bodyLineOffset ?? strippedLineOffset(entry.raw, entry.body.text);
+  return unknownContainers(entry.expanded?.text ?? entry.body.text).map(
+    ({ line, name }) => {
+      const origin = entry.expanded?.origins[line - 1];
+      return {
+        code: "BLUME_UNKNOWN_DIRECTIVE",
+        file: origin?.file ?? page,
+        line: origin?.line ?? line + offset,
+        message: `\`:::${name}\` isn't a callout type, so the page shows its \`:::\` lines as written around its content.`,
+        severity: "warning",
+        suggestion: `Use a callout type — ${CALLOUT_NAMES} — or remove the \`:::\` lines to keep the content as plain prose.`,
+      };
+    }
+  );
+};

package/src/core/frontmatter.ts

@@ -19,13 +19,18 @@ type StringifyArgs = Parameters<typeof baseMatter.stringify>;
 /** Front matter data as gray-matter types it (`GrayMatterFile["data"]`). */
 type FrontMatterData = ReturnType<typeof baseMatter>["data"];
 
+/** A YAML load result: a mapping (or list) Astro keeps as front matter data. */
+const isYamlCollection = (
+  value: ReturnType<typeof load>
+): value is FrontMatterData => typeof value === "object" && value !== null;
+
 const yamlEngine = {
-  // SAFETY: gray-matter's engine contract expects an object; a front matter
-  // block is a YAML mapping, and js-yaml returns a scalar only for degenerate
-  // input, which gray-matter treats the same way its bundled engine's output
-  // is treated.
-  parse: (input: string): object =>
-    (load(input, { schema: YAML_SCHEMA }) ?? {}) as object,
+  // A block that loads to a scalar (`title` alone, or prose between two
+  // `---` lines) is no metadata: Astro reads it as `{}`, and so does Blume.
+  parse: (input: string): FrontMatterData => {
+    const value = load(input, { schema: YAML_SCHEMA });
+    return isYamlCollection(value) ? value : {};
+  },
   stringify: (data: FrontMatterData): string => dump(data),
 };
 
@@ -45,23 +50,21 @@ const withYamlEngine = <O extends { engines?: object } | undefined>(
 
 /**
  * True when a document's leading `---` line is a CommonMark thematic break,
- * not a front matter fence. Two shapes qualify (mirroring
- * `linesWithoutFrontMatter` in `sources/normalize.ts`):
- *   - the next line is blank (or absent) — YAML metadata starts on the very
- *     next line, so a gap means the body *opens* with a divider (e.g. a
- *     Notion page whose first block is one);
- *   - no closing `---` line follows — gray-matter would swallow the whole
- *     document as one unclosed YAML block and hand it to js-yaml, which
- *     crashes on ordinary Markdown (`> quote` → "a line break is expected").
+ * not a front matter fence: no closing `---` line follows. Astro's own front
+ * matter match requires that close too, while gray-matter would swallow the
+ * whole document as one unclosed YAML block and hand it to js-yaml, which
+ * crashes on ordinary Markdown (`> quote` → "a line break is expected").
+ *
+ * A blank line after the opening `---` is still front matter: Astro strips
+ * the block from the page either way, so reading it as a divider here would
+ * ignore its `draft`, `slug`, and `hidden` while its YAML leaked into search
+ * and llms.txt.
  */
 const opensWithThematicBreak = (input: string): boolean => {
-  const [first = "", second] = input.split(/\r?\n/u, 2);
+  const [first = ""] = input.split(/\r?\n/u, 1);
   if (!/^-{3}\s*$/u.test(first)) {
     return false;
   }
-  if (second === undefined || second.trim() === "") {
-    return true;
-  }
   // gray-matter closes the block at the next line-leading `---`; matching its
   // search exactly keeps this guard from firing on any document it parses.
   return !input.includes("\n---", 1);

package/src/core/heading-markers.ts

@@ -55,17 +55,12 @@ export interface HeadingMarkers {
  * the heading count (mid-text brackets are ordinary prose); when a marker kind
  * repeats, the last one written wins.
  *
- * `isRefDefined` reports whether a link-reference definition exists for a
- * bracket's label (`toc`, `!toc`, `#id`): a defined bracket is a CommonMark
- * shortcut link, not a marker — the renderer sees a resolved `<a>` element
- * there and strips nothing at or before it, so the parse stops the same way.
- * The render-time hast plugin never passes it (resolved links are already
- * elements by the time it runs); the raw-source scanner does.
+ * Callers pass the heading's trailing text node after a Markdown parse, so a
+ * bracket that a link-reference definition turns into a CommonMark shortcut
+ * link (`[toc]` with a `[toc]: …` definition) is already an element there and
+ * never reaches this parse.
  */
-export const parseHeadingMarkers = (
-  text: string,
-  isRefDefined?: (label: string) => boolean
-): HeadingMarkers => {
+export const parseHeadingMarkers = (text: string): HeadingMarkers => {
   let remaining = text;
   let id: string | undefined;
   let toc: HeadingMarkers["toc"];
@@ -75,14 +70,6 @@ export const parseHeadingMarkers = (
     match = MARKER.exec(remaining)
   ) {
     const explicitId = match.groups.curlyId ?? match.groups.id;
-    const label =
-      explicitId === undefined
-        ? `${match.groups.hide ?? ""}toc`
-        : `#${explicitId}`;
-    // A `{#id}` is never a shortcut link, whatever the definitions say.
-    if (match.groups.curlyId === undefined && isRefDefined?.(label)) {
-      break;
-    }
     remaining = remaining.slice(0, match.index);
     if (explicitId === undefined) {
       // Stripping runs right-to-left, so keeping the first capture of each

package/src/core/i18n.ts

@@ -219,11 +219,31 @@ export const localeTargetPath = (
   return `${folder}/${rel}`;
 };
 
+/**
+ * The warning for a top-level folder named after the default locale
+ * (`docs/en/` when `defaultLocale` is `en`). Only non-default codes are
+ * locale folders — the default locale lives at the content root — so the
+ * folder is ordinary default-locale content, published one level down at
+ * `/en/…` (`/en/en/…` with the default prefix shown) and filled into every
+ * other locale at `/fr/en/…`.
+ */
+const defaultLocaleFolderDiagnostic = (
+  folder: string,
+  i18n: ResolvedI18nConfig
+): Diagnostic => ({
+  code: "BLUME_I18N_DEFAULT_LOCALE_FOLDER",
+  message: `Folder "${folder}/" is named after the default locale, but "${i18n.defaultLocale}" pages live at the content root — its pages publish at ${localizeRoute(`/${folder}`, i18n.defaultLocale, i18n)}/… instead.`,
+  severity: "warning",
+  suggestion: `Move the contents of "${folder}/" up to the content root; only the other locales get a folder.`,
+});
+
 /**
  * Warn about top-level content folders that look like a locale (a code Blume
  * recognizes) but aren't declared in `i18n.locales`. Without this they're
  * silently treated as default-locale content under a `/<code>/…` route, which
  * is almost never intended — usually a translation that wasn't registered.
+ * A folder named after the default locale gets the same treatment (see
+ * {@link defaultLocaleFolderDiagnostic}).
  */
 export const i18nDiagnostics = (
   pages: PageRecord[],
@@ -242,9 +262,17 @@ export const i18nDiagnostics = (
     // Inside a version snapshot the locale dir sits one level deeper
     // (`v1.0/fr/guide.md`), so a configured version segment is skipped first.
     const parts = page.source.ref.split("/");
-    const first = (
-      parts[0] && versionDirs.has(parts[0]) ? parts[1] : parts[0]
-    )?.toLowerCase();
+    const folder = parts[0] && versionDirs.has(parts[0]) ? parts[1] : parts[0];
+    const first = folder?.toLowerCase();
+    if (
+      folder !== undefined &&
+      first === i18n.defaultLocale.toLowerCase() &&
+      !seen.has(first)
+    ) {
+      seen.add(first);
+      diagnostics.push(defaultLocaleFolderDiagnostic(folder, i18n));
+      continue;
+    }
     if (
       first &&
       !seen.has(first) &&

package/src/core/last-modified.ts

@@ -1,6 +1,7 @@
 import { execFileSync } from "node:child_process";
+import { realpathSync } from "node:fs";
 
-import { relative } from "pathe";
+import { normalize, relative } from "pathe";
 
 import type { Diagnostic } from "./types.ts";
 
@@ -58,6 +59,23 @@ export const parseGitLog = (output: string): Map<string, string> => {
   return times;
 };
 
+/**
+ * `path` with every symlink resolved, the spelling git prints paths in: a
+ * project opened through a link (`/tmp/site` on macOS, where `/tmp` links to
+ * `/private/tmp`) gets `/private/tmp/site` from `rev-parse --show-toplevel`,
+ * so the project's own spelling would compare as outside the repository and
+ * every page would go undated. The native realpath also expands a Windows
+ * 8.3 short name (`RUNNER~1`), which git does too. A path that doesn't exist
+ * stays as written.
+ */
+export const realPath = (path: string): string => {
+  try {
+    return normalize(realpathSync.native(path));
+  } catch {
+    return path;
+  }
+};
+
 /**
  * The toplevel of the repository containing `root`, or null when git is
  * unavailable or the project isn't a repo. Callers use it to decide which
@@ -108,6 +126,10 @@ export const gitLastModifiedTimes = (
   if (gitRoot === null) {
     return new Map();
   }
+  // Git names paths by their real location, so the pathspecs and the paths
+  // read back against the log are compared in that spelling too (see
+  // `realPath`).
+  const top = realPath(gitRoot);
   try {
     const output = execFileSync(
       // oxlint-disable-next-line sonarjs/no-os-command-from-path -- git is a required dev-tool dependency resolved from PATH
@@ -121,14 +143,14 @@ export const gitLastModifiedTimes = (
         "--format=%x00%cI",
         "--name-only",
         "--",
-        ...contentRoots,
+        ...contentRoots.map(realPath),
       ],
       { encoding: "utf-8", env: gitEnv(), maxBuffer: 256 * 1024 * 1024 }
     );
     const byRepoPath = parseGitLog(output);
     const result = new Map<string, string>();
     for (const sourcePath of sourcePaths) {
-      const iso = byRepoPath.get(relative(gitRoot, sourcePath));
+      const iso = byRepoPath.get(relative(top, realPath(sourcePath)));
       if (iso) {
         result.set(sourcePath, iso);
       }

package/src/core/locale-links.ts

@@ -1,5 +1,6 @@
 import {
   isInternalPath,
+  mountBasePath,
   normalizePath,
   stripBasePath,
   withBasePath,
@@ -120,7 +121,10 @@ export const localizeHref = (
   if (localized === based) {
     return href;
   }
-  return `${withBasePath(options.deployBase, localized)}${suffix}`;
+  // The base came off above, so it goes back on unconditionally: a localized
+  // path that starts with the base's own name (`/ja/…` under base `/ja`) is
+  // still served under it.
+  return `${mountBasePath(options.deployBase, localized)}${suffix}`;
 };
 
 /** Every `<a …>` opening tag; `\s` keeps `<abbr>`/`<astro-island>` out. */

package/src/core/meta.ts

@@ -89,6 +89,38 @@ const withinInclude = (
     (pattern) => !pattern.startsWith("!") && onPathOf(dir, globBase(pattern))
   );
 
+/**
+ * The folder-meta files a filesystem source contributes: `patterns` (every
+ * meta module name, shared `meta.$.*` included, by default) under the source's
+ * root, minus its `exclude` globs, dependencies, and build output, and only in
+ * folders its `include` globs reach. `blume translate` finds the meta files it
+ * translates through this too, so it covers exactly the ones the scan reads.
+ */
+export const findFolderMetaFiles = async (
+  source: FolderMetaSource,
+  patterns: readonly string[] = META_FILES
+): Promise<string[]> => {
+  const found = await glob([...patterns], {
+    absolute: true,
+    cwd: source.root,
+    // Never descend into dependencies or build output — relevant when the
+    // root is the project root (e.g. a `.`-rooted or all-staged project).
+    // The source's own `exclude` applies too: a `meta.ts` under an excluded
+    // folder (`src/lib/meta.ts` beside `exclude: ["src/**"]`) is application
+    // code, not folder meta, and importing it would fail.
+    ignore: [
+      ...(source.exclude ?? []),
+      "**/node_modules/**",
+      "**/.blume/**",
+      "**/dist/**",
+    ],
+    onlyFiles: true,
+  });
+  return found.filter((file) =>
+    withinInclude(relative(source.root, dirname(file)), source.include)
+  );
+};
+
 /**
  * The folder-meta key for a directory. Mirrors the sidebar group path: the
  * source's route prefix (`docs`) followed by the directory relative to the
@@ -155,25 +187,7 @@ export const discoverFolderMeta = async (
   // `content.root` still contributes its folder meta.
   const perSource = await Promise.all(
     list.map(async (source) => {
-      const found = await glob(META_FILES, {
-        absolute: true,
-        cwd: source.root,
-        // Never descend into dependencies or build output — relevant when the
-        // root is the project root (e.g. a `.`-rooted or all-staged project).
-        // The source's own `exclude` applies too: a `meta.ts` under an
-        // excluded folder (`src/lib/meta.ts` beside `exclude: ["src/**"]`)
-        // is application code, not folder meta, and importing it would fail.
-        ignore: [
-          ...(source.exclude ?? []),
-          "**/node_modules/**",
-          "**/.blume/**",
-          "**/dist/**",
-        ],
-        onlyFiles: true,
-      });
-      const files = found.filter((file) =>
-        withinInclude(relative(source.root, dirname(file)), source.include)
-      );
+      const files = await findFolderMetaFiles(source);
       const loaded = await Promise.all(
         files.map(
           async (

package/src/core/navigation.ts

@@ -115,11 +115,29 @@ const numericOrder = (segment: string): number => {
   return value ? Math.trunc(Number(value)) : Number.POSITIVE_INFINITY;
 };
 
+/**
+ * The name inside a group folder's parentheses — `(guides)`, or `01-(guides)`
+ * with its ordering prefix outside them — else undefined. A prefix written
+ * inside (`(01-guides)`) stays in the name, where it sorts and drops like any
+ * folder's.
+ */
+const groupName = (raw: string): string | undefined =>
+  (raw.match(GROUP_FOLDER) ?? stripOrderingPrefix(raw).match(GROUP_FOLDER))
+    ?.groups?.label;
+
+/**
+ * A folder's sidebar order: its ordering prefix, or — for a group folder
+ * without one outside the parentheses — the prefix inside them, so
+ * `01-(guides)` and `(01-guides)` both sort like `01-guides`.
+ */
+const folderOrder = (raw: string): number =>
+  numericOrder(
+    orderingPrefix(raw) === undefined ? (groupName(raw) ?? raw) : raw
+  );
+
 /** The nav key of a raw path segment: group label or numeric-stripped name. */
-const segmentKey = (raw: string): string => {
-  const group = raw.match(GROUP_FOLDER)?.groups?.label;
-  return stripOrderingPrefix(group ?? raw);
-};
+const segmentKey = (raw: string): string =>
+  stripOrderingPrefix(groupName(raw) ?? raw);
 
 /**
  * Whether a filename stem is a directory index, ignoring an ordering prefix:
@@ -221,8 +239,8 @@ const ensureGroup = (
   const group = createGroup(
     segmentKey(rawSegment),
     path,
-    humanize(rawSegment.match(GROUP_FOLDER)?.groups?.label ?? rawSegment),
-    numericOrder(rawSegment)
+    humanize(groupName(rawSegment) ?? rawSegment),
+    folderOrder(rawSegment)
   );
   parent.index.set(rawSegment, group);
   parent.children.push(group);
@@ -722,7 +740,9 @@ const buildFileSystemSidebar = (
     const folderParts = isIndexStem(stem)
       ? routeSegments
       : routeSegments.slice(0, -1);
-    const routeDirCount = dirs.filter((dir) => !GROUP_FOLDER.test(dir)).length;
+    const routeDirCount = dirs.filter(
+      (dir) => groupName(dir) === undefined
+    ).length;
     const offset = Math.max(0, folderParts.length - routeDirCount);
     // A frontmatter `slug` publishes the page away from its folder, so its
     // route says nothing about where the folder lives (`guides/a.md` with
@@ -744,7 +764,7 @@ const buildFileSystemSidebar = (
     const folders: string[] = [];
     for (const dir of dirs) {
       parent = ensureGroup(parent, dir);
-      if (!GROUP_FOLDER.test(dir)) {
+      if (groupName(dir) === undefined) {
         consumed += 1;
         folders.push(stripOrderingPrefix(dir));
       }

package/src/core/project-graph.ts

@@ -3,6 +3,7 @@ import { isAbsolute, relative } from "pathe";
 import { CHANGELOG_INDEX_ROUTE, hasChangelogIndex } from "./changelog-index.ts";
 import { loadConfig } from "./config.ts";
 import { customStaticRoutes, discoverPages } from "./custom-pages.ts";
+import { unknownDirectiveDiagnostics } from "./directive-diagnostics.ts";
 import { buildContentGraph } from "./graph.ts";
 import { i18nDiagnostics } from "./i18n.ts";
 import { expandIncludes, hasIncludeStatements } from "./includes.ts";
@@ -10,6 +11,7 @@ import {
   gitLastModifiedTimes,
   gitRepositoryRoot,
   lastModifiedShallowWarning,
+  realPath,
   resolveLastModifiedConfig,
 } from "./last-modified.ts";
 import { buildManifest } from "./manifest.ts";
@@ -196,11 +198,34 @@ const normalizeLoadedEntries = (
       }
       pages.push(...normalized.pages);
       allDiagnostics.push(...normalized.diagnostics);
+      if (normalized.pages.length > 0) {
+        allDiagnostics.push(...unknownDirectiveDiagnostics(entry, source.name));
+      }
     }
   }
   return { diagnostics: allDiagnostics, droppedPages, pages };
 };
 
+/**
+ * The local sources' on-disk roots a `git log` pathspec can cover: those
+ * inside the repository at `gitRoot`. A root outside it would fail the log
+ * outright and can never yield dates. Compared by real path, since git spells
+ * its toplevel with every symlink resolved (`/private/tmp/site` for a project
+ * opened as `/tmp/site`); the roots themselves keep the project's spelling.
+ */
+const gitContentRoots = (
+  sources: readonly ContentSource[],
+  gitRoot: string | null
+): string[] => {
+  if (gitRoot === null) {
+    return [];
+  }
+  const top = realPath(gitRoot);
+  return sources
+    .flatMap((source) => (source.contentRoot ? [source.contentRoot] : []))
+    .filter((dir) => isWithin(top, realPath(dir)));
+};
+
 /**
  * Run the full core pipeline for a project root: load config, resolve paths,
  * discover content and folder meta, build the graph, and assemble the manifest.
@@ -362,12 +387,9 @@ export const scanProject = async (
     // The git pathspecs must cover where the pages actually live: each local
     // source's own on-disk root — a filesystem source's `root`, or a staged
     // local source's tree (an Obsidian vault) — which diverges from the global
-    // `content.root`. A root outside the repository would fail the log outright
-    // and can never yield dates, so those are dropped up front.
+    // `content.root`.
     const gitRoot = gitRepositoryRoot(context.root);
-    const contentRoots = sources
-      .flatMap((source) => (source.contentRoot ? [source.contentRoot] : []))
-      .filter((dir) => gitRoot !== null && isWithin(gitRoot, dir));
+    const contentRoots = gitContentRoots(sources, gitRoot);
     const gitTimes = gitLastModifiedTimes(
       context.root,
       contentRoots,

package/src/core/schema.ts

@@ -1303,9 +1303,9 @@ const ogConfigSchema = z.strictObject({
    */
   enabled: z.boolean().optional(),
   /**
-   * Google Font families for the generated card, extending Takumi's Latin-only
-   * default so non-Latin titles (CJK, and so on) render instead of tofu.
-   * Fetched from Google Fonts at build.
+   * Fonts for the generated card, replacing the default stack (Takumi's
+   * Latin-only built-in font plus a Noto fallback per script). Google
+   * families are fetched from Google Fonts at build.
    */
   fonts: z.array(ogFontSchema).optional(),
   /**
@@ -1687,6 +1687,20 @@ const DATE_FORM_FIELDS = [
   "day",
 ] as const;
 
+/**
+ * Whether `Intl` knows a time zone. An unknown one (`Asia/Tokio`) throws a
+ * RangeError the first time a date is formatted, deep in a page render, so it
+ * is caught here where the error can point at `dateFormat.timeZone`.
+ */
+const isKnownTimeZone = (timeZone: string): boolean => {
+  try {
+    Intl.DateTimeFormat("en", { timeZone });
+    return true;
+  } catch {
+    return false;
+  }
+};
+
 const dateFormatConfigSchema = z
   .strictObject({
     /** Calendar system (e.g. `japanese`, `buddhist`). */
@@ -1702,7 +1716,13 @@ const dateFormatConfigSchema = z
     /** Numbering system (e.g. `latn`, `arab`). */
     numberingSystem: z.string().optional(),
     /** IANA time zone (e.g. `Asia/Tokyo`). Defaults to `UTC`. */
-    timeZone: z.string().optional(),
+    timeZone: z
+      .string()
+      .refine(isKnownTimeZone, {
+        message:
+          'Unknown time zone; use an IANA name like "Asia/Tokyo" or "UTC".',
+      })
+      .optional(),
     /** Weekday representation. */
     weekday: z.enum(["long", "short", "narrow"]).optional(),
     /** Year representation. */