blume 1.7.2 → 2.0.0

package/src/core/diagnostics.ts

@@ -22,7 +22,7 @@ export const createDiagnostic = (diagnostic: Diagnostic): Diagnostic =>
 const DOCS_BASE = "https://useblume.dev";
 
 const DOCS_DEPLOYMENT = "/docs/deployment";
-const DOCS_REFERENCE_CLI = "/docs/reference/cli";
+const DOCS_CLI_VALIDATE = "/docs/cli/validate";
 const DOCS_CONTENT_SOURCES = "/docs/content/sources";
 const DOCS_CONTENT_NAVIGATION = "/docs/content/navigation";
 const DOCS_CONTENT_INCLUDES = "/docs/content/includes";
@@ -31,19 +31,22 @@ const DOCS_CONTENT_INCLUDES = "/docs/content/includes";
 const DOCS_PATHS = new Map(
   Object.entries({
     BLUME_ADAPTER_REQUIRED: DOCS_DEPLOYMENT,
-    BLUME_ASSETS_UNCHECKED: DOCS_REFERENCE_CLI,
+    BLUME_ASSETS_UNCHECKED: DOCS_CLI_VALIDATE,
     BLUME_ASSET_FETCH_FAILED: DOCS_CONTENT_SOURCES,
-    BLUME_BROKEN_ANCHOR: DOCS_REFERENCE_CLI,
-    BLUME_BROKEN_ASSET: DOCS_REFERENCE_CLI,
-    BLUME_BROKEN_LINK: DOCS_REFERENCE_CLI,
+    BLUME_BROKEN_ANCHOR: DOCS_CLI_VALIDATE,
+    BLUME_BROKEN_ASSET: DOCS_CLI_VALIDATE,
+    BLUME_BROKEN_LINK: DOCS_CLI_VALIDATE,
+    BLUME_COMPONENTS_INVALID: "/docs/configuration/customization",
     BLUME_CONFIG_INVALID: "/docs/configuration",
     BLUME_CONFIG_LOAD_FAILED: "/docs/configuration",
     BLUME_CONTENT_ROOT_MISSING: DOCS_CONTENT_SOURCES,
-    BLUME_DEAD_LINK: DOCS_REFERENCE_CLI,
+    BLUME_DEAD_LINK: DOCS_CLI_VALIDATE,
+    BLUME_DEPENDENCY_MISSING: "/docs/cli/doctor",
     BLUME_DUPLICATE_ROUTE: DOCS_CONTENT_NAVIGATION,
     BLUME_DUPLICATE_SIDEBAR_ORDER: DOCS_CONTENT_NAVIGATION,
-    BLUME_FRONTMATTER_INVALID: "/docs/reference/frontmatter",
+    BLUME_FRONTMATTER_INVALID: "/docs/content/frontmatter",
     BLUME_INCLUDE_CYCLE: DOCS_CONTENT_INCLUDES,
+    BLUME_INCLUDE_MALFORMED: DOCS_CONTENT_INCLUDES,
     BLUME_INCLUDE_NOT_FOUND: DOCS_CONTENT_INCLUDES,
     BLUME_INCLUDE_OUTSIDE_ROOT: DOCS_CONTENT_INCLUDES,
     BLUME_MDX_CURLY_ANCHOR: "/docs/content/syntax",
@@ -63,10 +66,14 @@ const DOCS_PATHS = new Map(
     BLUME_SOURCE_OFFLINE: DOCS_CONTENT_SOURCES,
     BLUME_SOURCE_SDK_MISSING: DOCS_CONTENT_SOURCES,
     BLUME_SOURCE_UNAVAILABLE: DOCS_CONTENT_SOURCES,
+    BLUME_TRANSLATE_MISSING: "/docs/cli/translate",
+    BLUME_TRANSLATE_STALE: "/docs/cli/translate",
     BLUME_UNKNOWN_COMPONENT: "/docs/configuration/customization",
     BLUME_UNKNOWN_ICON: DOCS_CONTENT_NAVIGATION,
+    BLUME_UNKNOWN_OPTION: "/docs/cli",
     BLUME_WIKILINK_AMBIGUOUS: DOCS_CONTENT_SOURCES,
     BLUME_WIKILINK_UNRESOLVED: DOCS_CONTENT_SOURCES,
+    BLUME_YARN_PNP: "/docs/quickstart",
   })
 );
 

package/src/core/graph.ts

@@ -1,5 +1,9 @@
 import { withBasePath } from "./base-path.ts";
-import { localizeRoute, resolveFallbackLocale } from "./i18n.ts";
+import {
+  localizeInternalPath,
+  localizeRoute,
+  resolveFallbackLocale,
+} from "./i18n.ts";
 import { validateNavIcons, validateNavStructure } from "./nav-diagnostics.ts";
 import { buildNavigation } from "./navigation.ts";
 import type {
@@ -21,6 +25,10 @@ import { versionizeRoute } from "./versions.ts";
 interface BuildContentGraphOptions {
   /** Site-wide route mount point (`""` or `/seg`); invisible to the nav tree. */
   basePath?: string;
+  /** The header brand link as configured (`logo.href`, default `/`). */
+  brandHref?: string;
+  /** Routes served outside the content tree that tabs may link to directly. */
+  extraRoutes?: ReadonlySet<string>;
   folderMeta: Map<string, FolderMeta>;
   sharedFolderMeta?: Map<string, FolderMeta>;
   navigation: ResolvedConfig["navigation"];
@@ -138,17 +146,54 @@ const buildLocaleNavigation = (
   diagnostics: Diagnostic[],
   version = ""
 ): Navigation => {
-  // Localize internal tab paths — the tab's own and its dropdown items' — so a
-  // header tab points to its in-locale route (e.g. `/docs` -> `/fr/docs`);
-  // external paths pass through. Selectors are left alone: a language
-  // selector's items intentionally target specific locales.
-  // `//host/path` is protocol-relative — an external URL that happens to start
-  // with a slash, so it must not pick up a locale prefix. `withBasePath` draws
-  // the same line for the same reason.
-  const localizePath = (path: string): string =>
-    path.startsWith("/") && !path.startsWith("//")
-      ? localizeRoute(path, code, i18n)
+  const basePath = options.basePath ?? "";
+  const real = pages.filter((page) => page.locale === code);
+  const localePages = localePagesFor(
+    code,
+    real,
+    fallback,
+    fallbackByKey,
+    i18n,
+    basePath
+  );
+  // Every route the build serves: each locale's pages (this locale's fallback
+  // copies included) plus the routes outside the content tree — custom pages
+  // and the generated changelog index, which mount outside `basePath`.
+  const pageRoutes = [
+    ...new Set([...pages, ...localePages].map((page) => page.route)),
+  ];
+  const extraRoutes = options.extraRoutes ?? new Set<string>();
+  // Whether `path` (authored at root, like a tab path) is served — exactly, or
+  // with `section`, as the prefix of a served page (a tab resolves to its
+  // section's first page, a plain link doesn't).
+  const serves = (path: string, section: boolean): boolean => {
+    if (extraRoutes.has(path)) {
+      return true;
+    }
+    const based = withBasePath(basePath, path);
+    const prefix = based === "/" ? "/" : `${based}/`;
+    return pageRoutes.some(
+      (route) => route === based || (section && route.startsWith(prefix))
+    );
+  };
+  // Localize an internal link so it points to its in-locale route (e.g. `/docs`
+  // -> `/fr/docs`); external paths pass through. A route this locale doesn't
+  // serve while the default one does — a custom page, the generated changelog
+  // index — exists only at its own path, so the link stays there instead of
+  // 404ing. Tab paths (and their dropdown items') resolve to a section's first
+  // page, so a translated section counts; hrefs must be served exactly.
+  // Selectors are left alone: a language selector's items intentionally target
+  // specific locales. The header's brand link resolves the same way, so the
+  // logo and the tabs beside it always agree on the reader's locale.
+  const localizeServed = (path: string, section: boolean): string => {
+    const localized = localizeInternalPath(path, code, i18n);
+    return localized === path ||
+      serves(localized, section) ||
+      !serves(path, section)
+      ? localized
       : path;
+  };
+  const localizePath = (path: string): string => localizeServed(path, true);
   const tabs = resolveTabLabels(
     options.navigation.tabs,
     code,
@@ -163,19 +208,10 @@ const buildLocaleNavigation = (
       path: localizePath(tab.path),
     };
     if (localized.href) {
-      localized.href = localizePath(localized.href);
+      localized.href = localizeServed(localized.href, false);
     }
     return localized;
   });
-  const real = pages.filter((page) => page.locale === code);
-  const localePages = localePagesFor(
-    code,
-    real,
-    fallback,
-    fallbackByKey,
-    i18n,
-    options.basePath ?? ""
-  );
   // Meta files live in locale directories only under the `dir` parser
   // (`fr/guides/meta.ts` -> key `fr/guides`). Under `dot`, translations sit
   // next to the originals and `guides/meta.ts` applies to every locale —
@@ -188,16 +224,17 @@ const buildLocaleNavigation = (
   // locale, not kick them back to the default one.
   const localizeHref = <T extends { href: string }>(item: T): T => ({
     ...item,
-    href: localizePath(item.href),
+    href: localizeServed(item.href, false),
   });
   const { actions, cta, featured } = options.navigation;
 
-  return buildNavigation(localePages, {
+  const navigation = buildNavigation(localePages, {
     actions: actions?.map(localizeHref),
-    basePath: options.basePath ?? "",
+    basePath,
     cta: cta ? localizeHref(cta) : null,
     diagnostics,
     display: options.navigation.sidebar.display,
+    extraRoutes: options.extraRoutes,
     featured: featured?.map(localizeHref),
     folderMeta: options.folderMeta,
     // The localized tree root ("/" for the hidden default, "/fr" otherwise;
@@ -217,6 +254,9 @@ const buildLocaleNavigation = (
     sidebar: version ? undefined : options.navigation.sidebar.items,
     tabs,
   });
+  return options.brandHref === undefined
+    ? navigation
+    : { ...navigation, brandHref: localizeServed(options.brandHref, false) };
 };
 
 /**
@@ -234,10 +274,12 @@ const buildI18nNavigation = (
   // Pages of the fallback locale, by translation key — used to fill in a
   // locale's sidebar for pages it hasn't translated yet.
   const fallback = resolveFallbackLocale(i18n);
+  // Monolingual pages (GitHub releases) are left out: they aren't served at the
+  // other locales' URLs (see the route manifest), so no sidebar may link there.
   const fallbackByKey = new Map<string, PageRecord>();
   if (fallback) {
     for (const page of pages) {
-      if (page.locale === fallback) {
+      if (page.locale === fallback && !page.monolingual) {
         fallbackByKey.set(page.translationKey, page);
       }
     }
@@ -298,6 +340,7 @@ const buildVersionNavigation = (
       cta: options.navigation.cta,
       diagnostics,
       display: options.navigation.sidebar.display,
+      extraRoutes: options.extraRoutes,
       featured: options.navigation.featured,
       folderMeta: options.folderMeta,
       localizedRoot: versionizeRoute("/", id),
@@ -345,6 +388,7 @@ export const buildContentGraph = (
       cta: options.navigation.cta,
       diagnostics,
       display: options.navigation.sidebar.display,
+      extraRoutes: options.extraRoutes,
       featured: options.navigation.featured,
       folderMeta: options.folderMeta,
       selectors: options.navigation.selectors,

package/src/core/i18n-ui.ts

@@ -68,13 +68,15 @@ const uiStringsObject = z.object({
         .default(
           "Product updates, new features, and fixes from every release."
         ),
-      // `{version}` is replaced with the major line ("2.x") at render time.
-      showReleases: z.string().default("Show {version} releases"),
       title: z.string().default("Changelog"),
     })
     .prefault({}),
   content: z
     .object({
+      // A `<Color.Item>` swatch's accessible name; `{name}` and `{value}` are
+      // replaced with the color's name and the value it shows.
+      copyColor: z.string().default("Copy {name} color {value}"),
+      copyPrompt: z.string().default("Copy prompt"),
       diagramError: z.string().default("Could not render this diagram."),
     })
     .prefault({}),
@@ -101,6 +103,8 @@ const uiStringsObject = z.object({
       featured: z.string().default("Featured"),
       githubRepository: z.string().default("GitHub repository"),
       navigation: z.string().default("Navigation"),
+      // The screen-reader description every new-tab link points at.
+      opensInNewTab: z.string().default("Opens in a new tab"),
       primary: z.string().default("Primary"),
       sections: z.string().default("Sections"),
       toggleNavigation: z.string().default("Toggle navigation"),

package/src/core/i18n.ts

@@ -79,6 +79,23 @@ export const localizeRoute = (
   return logicalRoute === "/" ? prefix : `${prefix}${logicalRoute}`;
 };
 
+/**
+ * Localize a configured link target the way header tabs are: a root-relative
+ * internal path (`/`, `/docs`) moves into `code`'s prefix, and anything else —
+ * an absolute URL, a fragment, a relative path — passes through. `//host/path`
+ * is protocol-relative, an external URL that happens to start with a slash, so
+ * it must not pick up a locale prefix (`withBasePath` draws the same line).
+ * With no i18n (`null`) the path is returned as-is.
+ */
+export const localizeInternalPath = (
+  path: string,
+  code: string,
+  i18n: LocaleRouting | null
+): string =>
+  i18n && path.startsWith("/") && !path.startsWith("//")
+    ? localizeRoute(path, code, i18n)
+    : path;
+
 /**
  * Detect a leading non-default locale directory in a path's segments. The
  * default locale lives at the content root, so only non-default codes are

package/src/core/includes.ts

@@ -141,6 +141,100 @@ export const parseIncludeStatement = (
 export const parseIncludeLine = (line: string): IncludeStatement | null =>
   INDENTED_CODE.test(line) ? null : parseIncludeStatement(line.trim());
 
+/** A line that opens an include statement: `<include`, then a space, `>`, or its end. */
+const INCLUDE_OPEN = /^<include(?:[\s>]|$)/u;
+
+/** A line that closes one. */
+const INCLUDE_CLOSE = /<\/include\s*>$/u;
+
+/**
+ * How many lines a wrapped statement may span: room for a formatter that puts
+ * every attribute on its own line, short enough that an unclosed `<include`
+ * can't reach across a page.
+ */
+const MAX_STATEMENT_LINES = 8;
+
+/** What a line that may open an include statement turned out to be. */
+export type IncludeMatch =
+  /** A statement, ending on line `end` (the same line when it isn't wrapped). */
+  | { kind: "statement"; end: number; statement: IncludeStatement }
+  /** A line that opens `<include` but no statement Blume can read. */
+  | { kind: "malformed" }
+  /** Not an include statement at all. */
+  | { kind: "none" };
+
+/**
+ * Read the include statement opening at `lines[index]`, if any. A statement
+ * sits on a line of its own, or — as a formatter wraps a long one — runs from a
+ * line opening `<include` to the next line closing `</include>`, with no blank
+ * line between (the path on its own line, attributes on one line or several):
+ *
+ * ```mdx
+ * <include lang="ts" meta='title="config.ts"'>
+ *   ./examples/config.ts
+ * </include>
+ * ```
+ *
+ * The lines' trimmed text joins into the one-line form, so both parse by the
+ * same rules. In `.md` a first line indented like code is a code block, never
+ * a statement. A line that opens `<include` but doesn't close into a
+ * statement is `malformed`, so the author hears about it instead of the page
+ * rendering the raw tag. Shared by the string-level scanner and the render
+ * plugin so they splice exactly the same statements.
+ */
+export const matchIncludeStatement = (
+  lines: readonly string[],
+  index: number,
+  format: "md" | "mdx"
+): IncludeMatch => {
+  const first = lines[index] ?? "";
+  if (format === "md" && INDENTED_CODE.test(first)) {
+    return { kind: "none" };
+  }
+  const opening = first.trim();
+  if (!INCLUDE_OPEN.test(opening)) {
+    return { kind: "none" };
+  }
+  const single = parseIncludeStatement(opening);
+  if (single) {
+    return { end: index, kind: "statement", statement: single };
+  }
+  const parts = [opening];
+  const last = Math.min(lines.length, index + MAX_STATEMENT_LINES) - 1;
+  for (let end = index + 1; end <= last; end += 1) {
+    const part = (lines[end] ?? "").trim();
+    if (part === "") {
+      break;
+    }
+    parts.push(part);
+    if (INCLUDE_CLOSE.test(part)) {
+      const statement = parseIncludeStatement(parts.join(" "));
+      return statement
+        ? { end, kind: "statement", statement }
+        : { kind: "malformed" };
+    }
+  }
+  return { kind: "malformed" };
+};
+
+/**
+ * The warning for a line that opens `<include` but isn't a statement Blume can
+ * read — it renders as written, so a silent miss would ship a raw tag.
+ */
+export const malformedIncludeDiagnostic = (
+  file: string,
+  line: number
+): Diagnostic => ({
+  code: "BLUME_INCLUDE_MALFORMED",
+  file,
+  line,
+  message:
+    "This <include> isn't a statement Blume can read, so the page shows it as written.",
+  severity: "warning",
+  suggestion:
+    "Write <include>./path.mdx</include> on a line of its own, or wrap it with the path on its own line and no blank lines; only lang and meta attributes are read.",
+});
+
 /**
  * Advance the HTML comment state across one `.md` line — the render plugin's
  * half of the comment rule (a statement inside `<!-- -->` never splices),
@@ -432,67 +526,82 @@ const expandStatement = async (
 };
 
 /**
- * Walk a document's lines, replacing each include statement (outside fenced
- * code, comments, and — in `.md` — indented code blocks) with the target's
- * expanded lines. Statements that error stay verbatim so downstream surfaces
- * show what the author wrote; a blank line is padded around each splice so a
- * partial can't merge into an adjacent paragraph.
+ * Pass 1 of {@link expandLines}: find each include statement (outside fenced
+ * code, comments, and — in `.md` — indented code blocks), indexed by the line
+ * it opens on. A commented-out statement never renders, so expanding it would
+ * leak the partial into search/mirror surfaces the page doesn't show.
+ * Indented code and setext underlines only exist in `.md` (MDX has neither,
+ * and an indented `<include>` there is still JSX flow the renderer splices).
  */
-const expandLines = async (
-  body: string,
-  filePath: string,
-  lineOffset: number,
-  ctx: ExpandContext,
-  stack: readonly string[]
-): Promise<ExpandedLines> => {
-  const sourceLines = body.split("\n");
-  const isMdx = extname(filePath).toLowerCase() === ".mdx";
+const scanStatements = (
+  sourceLines: string[],
+  isMdx: boolean
+): (IncludeMatch | null)[] => {
   const delimiters = COMMENT_DELIMITERS[isMdx ? "mdx" : "md"];
-
-  // Pass 1: statement detection per line, tracking fenced code and comments —
-  // a commented-out statement never renders, so expanding it would leak the
-  // partial into search/mirror surfaces the page doesn't show. Indented code
-  // and setext underlines only exist in `.md` (MDX has neither, and an
-  // indented `<include>` there is still JSX flow the renderer splices).
+  const format = isMdx ? "mdx" : "md";
+  const matches: (IncludeMatch | null)[] = sourceLines.map(() => null);
   let fence: FenceState = null;
   let inComment = false;
-  const statements = sourceLines.map((line, index) => {
+  for (let index = 0; index < sourceLines.length; index += 1) {
+    const line = sourceLines[index] ?? "";
     if (inComment) {
       inComment = advanceCommentState(line, delimiters, true);
-      return null;
+      continue;
     }
     const next = nextFenceState(line, fence);
     const inFence = fence !== null || next !== null;
     fence = next;
     if (inFence) {
-      return null;
+      continue;
     }
     inComment = advanceCommentState(line, delimiters, false);
     if (inComment || !hasIncludeStatements(line)) {
-      return null;
+      continue;
     }
-    const statement = isMdx
-      ? parseIncludeStatement(line.trim())
-      : parseIncludeLine(line);
-    // A setext underline directly below folds the statement line into a
-    // heading — the renderer shows a heading, not a splice, so skip it.
+    const match = matchIncludeStatement(sourceLines, index, format);
+    // A setext underline directly below folds the statement into a heading —
+    // the renderer shows a heading, not a splice, so skip it.
     if (
-      statement &&
+      match.kind === "statement" &&
       !isMdx &&
-      SETEXT_UNDERLINE.test(sourceLines[index + 1] ?? "")
+      SETEXT_UNDERLINE.test(sourceLines[match.end + 1] ?? "")
     ) {
-      return null;
+      continue;
     }
-    return statement;
-  });
+    matches[index] = match;
+    if (match.kind === "statement") {
+      // A wrapped statement's remaining lines belong to it.
+      index = match.end;
+    }
+  }
+  return matches;
+};
+
+/**
+ * Walk a document's lines, replacing each include statement (outside fenced
+ * code, comments, and — in `.md` — indented code blocks) with the target's
+ * expanded lines. Statements that error stay verbatim so downstream surfaces
+ * show what the author wrote; a blank line is padded around each splice so a
+ * partial can't merge into an adjacent paragraph.
+ */
+const expandLines = async (
+  body: string,
+  filePath: string,
+  lineOffset: number,
+  ctx: ExpandContext,
+  stack: readonly string[]
+): Promise<ExpandedLines> => {
+  const sourceLines = body.split("\n");
+  const isMdx = extname(filePath).toLowerCase() === ".mdx";
+  const matches = scanStatements(sourceLines, isMdx);
 
   // Pass 2: expand every statement concurrently — reads are independent, and
   // each branch carries its own cycle stack.
   const expansions = await Promise.all(
-    statements.map((statement, index) =>
-      statement
+    matches.map((match, index) =>
+      match?.kind === "statement"
         ? expandStatement(
-            statement,
+            match.statement,
             filePath,
             lineOffset + index + 1,
             ctx,
@@ -506,9 +615,14 @@ const expandLines = async (
   // accumulated output, and error order should follow document order.
   const lines: string[] = [];
   const origins: LineOrigin[] = [];
-  for (const [index, line] of sourceLines.entries()) {
+  for (let index = 0; index < sourceLines.length; index += 1) {
+    const line = sourceLines[index] ?? "";
     const rawLine = lineOffset + index + 1;
+    const match = matches[index];
     const expanded = expansions[index];
+    if (match?.kind === "malformed") {
+      ctx.errors.push(malformedIncludeDiagnostic(filePath, rawLine));
+    }
     if (!expanded || "error" in expanded) {
       if (expanded) {
         ctx.errors.push(expanded.error);
@@ -526,6 +640,10 @@ const expandLines = async (
     }
     lines.push(...expanded.lines);
     origins.push(...expanded.origins);
+    // A wrapped statement's remaining lines were spliced with it.
+    if (match?.kind === "statement") {
+      index = match.end;
+    }
     if (sourceLines[index + 1]?.trim()) {
       pad();
     }

package/src/core/last-modified.ts

@@ -31,18 +31,13 @@ const gitEnv = (): NodeJS.ProcessEnv =>
     Object.entries(process.env).filter(([key]) => !GIT_LOCATION_VARS.has(key))
   );
 
-/** Normalize the `lastModified` config union into `{ enabled, source }`. */
+/** Normalize the `lastModified` config (`false | "git" | "frontmatter"`) into `{ enabled, source }`. */
 export const resolveLastModifiedConfig = (
-  value: boolean | { type: "git" | "frontmatter" }
-): ResolvedLastModified => {
-  if (value === false) {
-    return { enabled: false, source: "git" };
-  }
-  if (value === true) {
-    return { enabled: true, source: "git" };
-  }
-  return { enabled: true, source: value.type };
-};
+  value: false | "git" | "frontmatter"
+): ResolvedLastModified =>
+  value === false
+    ? { enabled: false, source: "git" }
+    : { enabled: true, source: value };
 
 /**
  * Parse `git log --format=%x00%cI --name-only` output into a map of