blume 1.1.0 → 1.1.2

package/src/core/project-graph.ts

@@ -15,7 +15,7 @@ import { resolveProjectContext } from "./project.ts";
 import type { ResolvedConfig } from "./schema.ts";
 import { normalizeEntry } from "./sources/normalize.ts";
 import { resolveDocsCollection, resolveSources } from "./sources/resolve.ts";
-import type { ContentSource } from "./sources/types.ts";
+import type { ContentSource, SourceLoadResult } from "./sources/types.ts";
 import type {
   BlumeManifest,
   ContentGraph,
@@ -70,6 +70,8 @@ export interface BlumeProject {
   graph: ContentGraph;
   manifest: BlumeManifest;
   diagnostics: Diagnostic[];
+  /** Entries excluded from the graph because their frontmatter failed validation. */
+  droppedPages: number;
   /** The instantiated content sources, for lazy entry reads (search/AI/raw). */
   sources: ContentSource[];
 }
@@ -116,6 +118,51 @@ const entryIdDiagnostics = (
   return diagnostics;
 };
 
+/**
+ * Funnel every loaded source's entries through the shared `normalizeEntry`,
+ * collecting pages, diagnostics, and the count of entries dropped outright —
+ * an entry that yields no pages but did yield diagnostics was rejected for
+ * invalid frontmatter, and callers surface that count so a build with missing
+ * pages can't read as clean.
+ */
+const normalizeLoadedEntries = (
+  loaded: ({ source: ContentSource } & SourceLoadResult)[],
+  config: ResolvedConfig
+): { pages: PageRecord[]; diagnostics: Diagnostic[]; droppedPages: number } => {
+  // Only thread `frontmatter.extend` through when a project opts in, so the
+  // known-key split in `normalizeEntry` stays off the default path.
+  const frontmatterExtend =
+    Object.keys(config.frontmatter.extend).length > 0
+      ? config.frontmatter.extend
+      : undefined;
+
+  const pages: PageRecord[] = [];
+  const allDiagnostics: Diagnostic[] = [];
+  let droppedPages = 0;
+  for (const { source, entries, diagnostics } of loaded) {
+    allDiagnostics.push(...diagnostics);
+    for (const entry of entries) {
+      const normalized = normalizeEntry(entry, {
+        basePath: config.basePath,
+        defaultType: config.content.defaultType,
+        frontmatterExtend,
+        i18n: config.i18n,
+        source: {
+          name: source.name,
+          prefix: source.prefix,
+          staged: source.staged,
+        },
+      });
+      if (normalized.pages.length === 0 && normalized.diagnostics.length > 0) {
+        droppedPages += 1;
+      }
+      pages.push(...normalized.pages);
+      allDiagnostics.push(...normalized.diagnostics);
+    }
+  }
+  return { diagnostics: allDiagnostics, droppedPages, pages };
+};
+
 /**
  * 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.
@@ -190,33 +237,11 @@ export const scanProject = async (
     discoverFolderMeta(metaSources, { localeDirs }),
   ]);
 
-  // Only thread `frontmatter.extend` through when a project opts in, so the
-  // known-key split in `normalizeEntry` stays off the default path.
-  const frontmatterExtend =
-    Object.keys(config.frontmatter.extend).length > 0
-      ? config.frontmatter.extend
-      : undefined;
-
-  const allPages: PageRecord[] = [];
-  const contentDiagnostics: Diagnostic[] = [];
-  for (const { source, entries, diagnostics } of loaded) {
-    contentDiagnostics.push(...diagnostics);
-    for (const entry of entries) {
-      const normalized = normalizeEntry(entry, {
-        basePath: config.basePath,
-        defaultType: config.content.defaultType,
-        frontmatterExtend,
-        i18n: config.i18n,
-        source: {
-          name: source.name,
-          prefix: source.prefix,
-          staged: source.staged,
-        },
-      });
-      allPages.push(...normalized.pages);
-      contentDiagnostics.push(...normalized.diagnostics);
-    }
-  }
+  const {
+    diagnostics: contentDiagnostics,
+    droppedPages,
+    pages: allPages,
+  } = normalizeLoadedEntries(loaded, config);
 
   // Drafts render in dev and in preview, but are excluded from production builds.
   const pages =
@@ -267,6 +292,7 @@ export const scanProject = async (
       ...graph.diagnostics,
       ...i18nWarnings,
     ],
+    droppedPages,
     graph,
     manifest,
     mode,

package/src/core/schema.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 
 import type { ComponentMarkdown } from "../ai/component-markdown.ts";
+import type { CodeTheme } from "../markdown/themes.ts";
 import { normalizeRoute } from "../openapi/references.ts";
 import { normalizeXHandle } from "../seo/x-handle.ts";
 import { FONT_SLUGS, isFontSlug } from "../theme/fonts.ts";
@@ -870,6 +871,13 @@ const ogConfigSchema = z.strictObject({
   logo: z.string().optional(),
   /** Optional generated-card colors. */
   palette: ogPaletteSchema.optional(),
+  /**
+   * Card headlines for custom `.astro` pages, keyed by route (`"/"`, `"/cli"`).
+   * A custom page has no frontmatter to read, so its card is otherwise titled
+   * by humanizing its last URL segment (`/cli` → "Cli"); an entry here wins.
+   * Content pages always take their card headline from the page title.
+   */
+  titles: z.record(z.string(), z.string()).optional(),
 });
 
 const rssConfigSchema = z.strictObject({
@@ -943,9 +951,38 @@ const githubConfigSchema = z.strictObject({
   repo: z.string(),
 });
 
+const codeThemeSchema = z.custom<CodeTheme>((value) => {
+  if (typeof value === "string") {
+    return true;
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  // Token rules live in `settings` (Shiki's canonical field, also the TextMate
+  // form themes like createCssVariablesTheme() produce) or `tokenColors` (the
+  // VS Code spelling Shiki falls back to). A colors-only theme (editor fg/bg,
+  // no token rules) is also valid — Shiki renders it from `colors` alone. Each
+  // field present must have the right shape, and at least one must be present.
+  const theme = value as Record<string, unknown>;
+  const settingsValid =
+    theme.settings === undefined || Array.isArray(theme.settings);
+  const tokenColorsValid =
+    theme.tokenColors === undefined || Array.isArray(theme.tokenColors);
+  const colorsValid =
+    theme.colors === undefined ||
+    (typeof theme.colors === "object" &&
+      theme.colors !== null &&
+      !Array.isArray(theme.colors));
+  const hasContent =
+    theme.settings !== undefined ||
+    theme.tokenColors !== undefined ||
+    theme.colors !== undefined;
+  return settingsValid && tokenColorsValid && colorsValid && hasContent;
+}, "Expected a Shiki theme name or custom theme object");
+
 const codeBlockThemeSchema = z.strictObject({
-  dark: z.string().default("github-dark"),
-  light: z.string().default("github-light"),
+  dark: codeThemeSchema.default("github-dark"),
+  light: codeThemeSchema.default("github-light"),
 });
 
 const codeBlocksConfigSchema = z.strictObject({

package/src/core/sources/github-releases.ts

@@ -56,6 +56,63 @@ const LEADING_V = /^v/iu;
 const NON_SLUG = /[^a-z0-9]+/gu;
 const EDGE_DASHES = /^-+|-+$/gu;
 
+// `blume audit` grades meta descriptions against the 110–160 character search
+// snippet range (audit/types.ts thresholds), so the derived summary aims for
+// the longest word-boundary cut under the cap.
+const DESCRIPTION_MAX = 160;
+const DESCRIPTION_MIN = 110;
+
+const CODE_FENCE = /```[\s\S]*?```/gu;
+const HEADING_LINE = /^#{1,6}\s.*$/gmu;
+const LIST_MARK = /^\s*(?:[-*+]|\d+[.)])\s+/u;
+// Changesets-generated release bullets open with the changeset's short commit
+// hash (`- cf8fa22: Fix …`) — noise in a search snippet.
+const CHANGESET_HASH = /^[0-9a-f]{7,40}:\s+/u;
+const IMAGE = /!\[[^\]]*\]\([^)]*\)/gu;
+const LINK = /\[(?<text>[^\]]*)\]\([^)]*\)/gu;
+const INLINE_CODE = /`(?<code>[^`]+)`/gu;
+// Tag-shaped only: a bare `<` in prose must not swallow text up to a later `>`.
+const HTML_OR_JSX = /<\/?[a-zA-Z][^\n<>]*>|<\/?>/gu;
+const MARKDOWN_PUNCT = /[*_~>]+/gu;
+const WHITESPACE = /\s+/gu;
+const TRAILING_FRAGMENT = /[\s,;:.—–-]+$/u;
+
+/**
+ * Derive a meta description from release notes: markdown reduced to plain
+ * text — section headings ("### Patch Changes") and changesets' commit-hash
+ * bullet prefixes dropped — then cut at a word boundary to fit the search
+ * snippet cap. Undefined when the notes have no prose at all.
+ */
+const releaseDescription = (body: string): string | undefined => {
+  const text = body
+    .replaceAll(CODE_FENCE, " ")
+    .replaceAll(HEADING_LINE, "")
+    .split("\n")
+    .map((line) => line.replace(LIST_MARK, "").replace(CHANGESET_HASH, ""))
+    .join("\n")
+    .replaceAll(IMAGE, " ")
+    .replaceAll(LINK, "$<text>")
+    .replaceAll(INLINE_CODE, "$<code>")
+    .replaceAll(HTML_OR_JSX, " ")
+    .replaceAll(MARKDOWN_PUNCT, " ")
+    .replaceAll(WHITESPACE, " ")
+    .trim();
+  if (!text) {
+    return undefined;
+  }
+  if (text.length <= DESCRIPTION_MAX) {
+    return text;
+  }
+  // Cut before the cap at a word boundary (kept only when it doesn't drop the
+  // summary under the minimum), shed any dangling punctuation, and mark the cut.
+  const slice = text.slice(0, DESCRIPTION_MAX - 1);
+  const boundary = slice.lastIndexOf(" ");
+  const head = (
+    boundary >= DESCRIPTION_MIN ? slice.slice(0, boundary) : slice
+  ).replace(TRAILING_FRAGMENT, "");
+  return `${head}…`;
+};
+
 /** Slugify a tag into a stable, URL-safe source ref (`v1.2.0` -> `v1-2-0`). */
 const slugifyTag = (tag: string): string =>
   tag.toLowerCase().replaceAll(NON_SLUG, "-").replaceAll(EDGE_DASHES, "");
@@ -71,9 +128,10 @@ const githubHeaders = (): Headers => {
 };
 
 /**
- * Lower one release to a staged Markdown entry: the notes become the body and
+ * Lower one release to a staged Markdown entry: the notes become the body,
  * `type: changelog` frontmatter (title/date/version/category) drives the
- * generated `/changelog` timeline and RSS feed.
+ * generated `/changelog` timeline and RSS feed, and a summary derived from the
+ * notes becomes the release page's meta description.
  */
 const releaseToEntry = (release: GithubRelease): SourceEntry => {
   const version = release.tag_name.replace(LEADING_V, "");
@@ -81,9 +139,14 @@ const releaseToEntry = (release: GithubRelease): SourceEntry => {
   const date = release.published_at ?? release.created_at;
   const category = release.prerelease ? "Prerelease" : "Release";
   const body = (release.body ?? "").replaceAll("\r\n", "\n").trim();
+  // A summary in `seo.description` gives each release page a unique meta
+  // description (instead of the site-wide fallback) without also rendering the
+  // visible lede paragraph a top-level `description` would add.
+  const description = releaseDescription(body);
   const data = {
     changelog: { category, version },
     date,
+    ...(description ? { seo: { description } } : {}),
     title,
     type: "changelog",
   };

package/src/core/types.ts

@@ -108,6 +108,13 @@ export interface PageRecord {
    * `/guides/x`). Pages with the same key are translations of each other.
    */
   translationKey: string;
+  /**
+   * True for entries filled in from the fallback locale to pad a locale's
+   * navigation for pages it hasn't translated yet. The record's content —
+   * title included — belongs to the fallback locale, so per-locale content
+   * checks skip these.
+   */
+  fallback?: boolean;
   /**
    * Content-relative path with the leading locale directory stripped, used for
    * sidebar grouping so the locale dir is not surfaced as a nav group. Equals
@@ -220,6 +227,13 @@ export interface Navigation {
   tabs: NavTab[];
   selectors: NavSelector[];
   sidebar: NavNode[];
+  /**
+   * The tree root in final path space — localized and based (`/`, `/en`,
+   * `/docs`). Tab paths arrive in the same space, so the tab sitting at this
+   * path spans the whole tree and must be scoped as the root tab, not as a
+   * section tab. Absent on older serialized graphs; treat as `/`.
+   */
+  root?: string;
   /** Pinned links shown above the sidebar sections, unscoped by tab. */
   featured: FeaturedLink[];
   /** Repo URL for the header link, or null when hidden (`navigation.repo`). */

package/src/markdown/index.ts

@@ -21,6 +21,8 @@ import { tableWrapPlugin } from "./table-wrap.ts";
 import { DEFAULT_CODE_THEMES } from "./themes.ts";
 import type { CodeThemes } from "./themes.ts";
 
+export type { CodeTheme, CodeThemes } from "./themes.ts";
+
 /** A Shiki transformer, derived from the upstream factories' return type. */
 type ShikiTransformer = ReturnType<typeof transformerNotationDiff>;
 
@@ -37,6 +39,7 @@ export { calloutTypeFor } from "./directives.ts";
 export { headingAnchorPlugin } from "./heading-anchors.ts";
 export { mermaidPlugin } from "./mermaid.ts";
 export { packageInstallPlugin } from "./package-install.ts";
+export { blumeTwoslashTransformer } from "./twoslash.ts";
 
 /** Element type of Satteri's `mdastPlugins`, sourced from the (alpha) core. */
 type MdastPlugin = NonNullable<

package/src/markdown/inline-code.ts

@@ -64,7 +64,7 @@ type InlineHighlighter = (
     defaultColor: false;
     lang: string;
     structure: "inline";
-    themes: { dark: string; light: string };
+    themes: CodeThemes;
   }
 ) => Promise<{ children: HastNode[] }>;
 

package/src/markdown/themes.ts

@@ -6,6 +6,11 @@
  * single home for the github fallback used when nothing is configured.
  */
 
+import type { ThemeRegistrationAny } from "shiki";
+
+/** A bundled Shiki theme name or an inline custom Shiki theme definition. */
+export type CodeTheme = string | ThemeRegistrationAny;
+
 /**
  * A light/dark Shiki theme pair (`markdown.codeBlocks.theme`). A `type` (not an
  * `interface`) so it keeps the implicit index signature Shiki's `themes`
@@ -13,8 +18,8 @@
  */
 // oxlint-disable-next-line typescript/consistent-type-definitions -- interface loses the implicit index signature Shiki's `themes` param needs
 export type CodeThemes = {
-  dark: string;
-  light: string;
+  dark: CodeTheme;
+  light: CodeTheme;
 };
 
 /** The default pair, used when `markdown.codeBlocks.theme` is unset. */

package/src/markdown/twoslash.ts

@@ -0,0 +1,60 @@
+/**
+ * The Twoslash transformer for fenced code blocks, compiled with Blume's own
+ * pinned TypeScript instead of whatever copy the user's project hoists.
+ *
+ * The stock `transformerTwoslash` from `@shikijs/twoslash` resolves the
+ * ambient `typescript` package, which is whatever version the surrounding
+ * project installed. Under TypeScript 7 (the native tsgo compiler) the
+ * package's main export is a version stub with no classic compiler API — no
+ * `ts.sys`, no language service — and its `lib/` directory ships no
+ * `lib.*.d.ts` files, so Twoslash breaks the moment a fence uses it. Blume
+ * ships a classic `typescript` as its own runtime dependency, so this factory
+ * resolves that copy from inside the package and hands it to Twoslash
+ * explicitly (`tsModule` for the compiler, `tsLibDirectory` for the default
+ * lib files), leaving the user's project free to use any TypeScript version.
+ *
+ * Composed from the `core` entrypoints of both packages: the main `twoslash`
+ * entry eagerly imports the ambient `typescript` (harmless under TS7 — the
+ * stub loads fine — but pointless), and its `transformerTwoslash` wrapper
+ * forwards `tsModule` to `createTwoslasher` while dropping `tsLibDirectory`.
+ * The core entries import no `typescript` at all and take both options.
+ */
+
+import { createRequire } from "node:module";
+import path from "node:path";
+
+import { createTransformerFactory, rendererRich } from "@shikijs/twoslash/core";
+import type { ShikiTransformer } from "shiki";
+import { createTwoslasher } from "twoslash/core";
+import type TS from "typescript";
+
+const require = createRequire(import.meta.url);
+
+/**
+ * Twoslash transformer preconfigured for Blume: opt-in per fence via the
+ * `twoslash` meta keyword (explicitTrigger), compiling with Blume's own
+ * pinned classic TypeScript. The compiler is resolved lazily at call time —
+ * this runs once, at Astro config load — so merely importing this module
+ * never pays the TypeScript parse cost.
+ */
+export const blumeTwoslashTransformer = (): ShikiTransformer => {
+  const tsModule = require("typescript") as typeof TS;
+  const twoslasher = createTwoslasher({
+    // Match the stock transformer's default: fence snippets are authored
+    // bundler-style (extensionless relative imports, package imports).
+    compilerOptions: {
+      moduleResolution: tsModule.ModuleResolutionKind.Bundler,
+    },
+    // `require.resolve("typescript")` is the package's main entry,
+    // `lib/typescript.js`; its directory holds the `lib.*.d.ts` default libs.
+    tsLibDirectory: path.dirname(require.resolve("typescript")),
+    tsModule,
+    vfsRoot: process.cwd(),
+  });
+  return createTransformerFactory(
+    twoslasher,
+    rendererRich()
+  )({
+    explicitTrigger: true,
+  });
+};

package/src/registry/eject.ts

@@ -472,7 +472,9 @@ export const eject = async (
 
   if (config.seo.og.enabled) {
     files.push({
-      content: ogEndpointTemplate(customOgRoutes(pages, config.title)),
+      content: ogEndpointTemplate(
+        customOgRoutes(pages, config.title, config.seo.og.titles)
+      ),
       path: join(srcDir, "pages", "og", "[...slug].png.ts"),
     });
   }