blume 2.1.3 → 2.2.1

package/src/components/content/Changelog.astro

@@ -0,0 +1,189 @@
+---
+// The changelog index's release list: every visible `type: changelog` entry,
+// newest first, grouped by year, each row linking to its own page.
+//
+// The generated `/changelog` page renders this, and so can a hand-written page
+// that wants prose above the list — an introduction, a feed link — which the
+// generated page has no slot for. Only the list lives here: the heading and the
+// description belong to whoever owns the page, so an authored page writes its
+// own and the generated page keeps the translatable `changelog` strings.
+import { getCollection } from "astro:content";
+import data from "blume:data";
+
+import {
+  compareChangelogDates,
+  groupChangelogYears,
+  parseChangelogDate,
+  uniqueAnchorIds,
+} from "../../core/changelog-list.ts";
+import { resolveDateFormatOptions } from "../../core/date-format.ts";
+import { withMountedBase } from "../islands/base-path.ts";
+import { contentStrings } from "./content-strings.ts";
+
+const i18n = data.config.i18n;
+// The list is always the default locale's entries, whatever locale the page
+// sits in. Every other surface that publishes this list already works that way
+// — the generated page, the `/changelog.md` mirror, llms-full.txt, MCP
+// `get_page`, search — so a translated page listing its own locale's entries
+// would be the one surface disagreeing with the rest about which releases
+// exist. Releases are also commonly written once and left untranslated, in
+// which case a per-locale list is the same list with fallback copies anyway.
+// (The chrome around it still follows the reader: `strings` and the dates.)
+const locale = i18n ? i18n.defaultLocale : null;
+const { changelog: strings } = contentStrings(data, Astro.currentLocale);
+// The page's own language, for the row dates and year headings. On the
+// unprefixed generated `/changelog` Astro resolves the default locale.
+const readerLocale = i18n ? (Astro.currentLocale ?? i18n.defaultLocale) : "en";
+
+const dateFormatOptions = resolveDateFormatOptions(data.config.dateFormat);
+// The year heads each group, so a row shows the rest of the date: a preset
+// style keeps its month wording, a component format simply drops the year.
+const { dateStyle, year: _year, ...dateComponents } = dateFormatOptions;
+const rowDateFormat: Intl.DateTimeFormatOptions = dateStyle
+  ? {
+      ...dateComponents,
+      day: "numeric",
+      // `medium` abbreviates the month; every other preset spells it out, so a
+      // `long` site keeps reading "October 5" rather than dropping to "Oct 5".
+      month: dateStyle === "medium" ? "short" : "long",
+    }
+  : dateComponents;
+const formatRowDate = (date: Date) =>
+  new Intl.DateTimeFormat(readerLocale, rowDateFormat).format(date);
+const formatYear = (date: Date) =>
+  new Intl.DateTimeFormat(readerLocale, {
+    timeZone: dateFormatOptions.timeZone,
+    year: "numeric",
+  }).format(date);
+
+const slugify = (text: string) =>
+  text
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9]+/gu, "-")
+    .replaceAll(/^-+|-+$/gu, "") || "update";
+
+// Map each entry to its own page. The collection entry id matches the route
+// manifest's `entryId`, and the manifest carries a route per locale and per
+// archived version, all sharing that id — so a map over every route would keep
+// whichever came last: a Portuguese permalink on an unlocalized index, or a
+// row pointing into last year's archived docs. Keep the current docs of the
+// listed locale, never a fallback copy (which renders another locale's content
+// at this URL), and list an entry only when it has such a route, so a
+// translated changelog file does not add a second row for the same release.
+// These are the conditions `ai/changelog-markdown.ts` filters pages by, so the
+// rendered list and the Markdown mirror select the same releases.
+//
+// Keyed by collection and id together, the way the catch-all looks an entry up:
+// both collections id an entry by its file path, so a `releases/v1-0-0.md` on
+// disk and a staged release from a source named `releases` share an id while
+// rendering at different routes.
+const entryKey = (collection: string, id: string) => `${collection}:${id}`;
+const routeByEntry = new Map<string, string>();
+for (const route of data.routes) {
+  if (
+    route.version === "" &&
+    !route.fallback &&
+    (locale === null || route.locale === locale)
+  ) {
+    routeByEntry.set(entryKey(route.collection, route.entryId), route.path);
+  }
+}
+
+// Non-filesystem changelog sources (GitHub Releases) render through a parallel
+// `staged` collection, which exists only when such a source is configured — the
+// route manifest says whether to look, so the index folds those releases in
+// without a generator flag, and a page that reads only `docs` can't quietly
+// drop them.
+const hasStaged = data.routes.some((route) => route.collection === "staged");
+const entries = [
+  ...(await getCollection("docs")),
+  ...(hasStaged ? await getCollection("staged" as "docs") : []),
+].filter(
+  (entry) =>
+    entry.data.type === "changelog" &&
+    !entry.data.draft &&
+    !entry.data.sidebar?.hidden &&
+    // A route is required on every site, not only localized ones: without
+    // i18n the map still drops archived versions, and an entry with no
+    // current-docs route would otherwise be listed with a dead self-anchor
+    // while the Markdown mirror left it out.
+    routeByEntry.has(entryKey(entry.collection, entry.id))
+);
+
+const rows = entries
+  .map((entry) => {
+    const date = parseChangelogDate(entry.data.date ?? entry.data.changelog?.date);
+    const label =
+      entry.data.title ??
+      (entry.data.changelog?.version
+        ? `v${entry.data.changelog.version}`
+        : "Update");
+    const route = routeByEntry.get(entryKey(entry.collection, entry.id));
+    return {
+      date,
+      href: route ? withMountedBase(route) : null,
+      label,
+      tag: entry.data.changelog?.category ?? null,
+    };
+  })
+  .toSorted((a, b) => compareChangelogDates(a.date, b.date));
+
+const ids = uniqueAnchorIds(rows.map((row) => slugify(row.label)));
+const items = rows.map((row, index) => ({
+  date: row.date ? formatRowDate(row.date) : null,
+  dateTime: row.date ? row.date.toISOString().slice(0, 10) : null,
+  href: row.href,
+  id: ids[index] as string,
+  label: row.label,
+  tag: row.tag,
+  year: row.date ? formatYear(row.date) : null,
+}));
+
+const groups = groupChangelogYears(items, (item) => item.year);
+---
+
+{
+  items.length === 0 ? (
+    <p>{strings.empty}</p>
+  ) : (
+    <div class="not-prose mt-10 divide-y divide-border border-border border-y">
+      {groups.map((group) => (
+        <section
+          aria-label={group.year ?? undefined}
+          class="grid md:grid-cols-[6rem_minmax(0,1fr)] md:gap-x-8"
+        >
+          <h2 class="mt-0! pt-3! font-medium! text-muted-foreground text-sm! leading-5! tabular-nums max-md:pb-1">
+            {group.year}
+          </h2>
+          <ul class="m-0! list-none divide-y divide-border p-0!">
+            {group.items.map((item) => (
+              <li class="m-0! p-0!" id={item.id}>
+                <a
+                  class="group/release flex items-baseline gap-4 py-3 no-underline! hover:no-underline!"
+                  href={item.href ?? `#${item.id}`}
+                >
+                  <span class="min-w-0 flex-1 font-medium text-foreground text-sm transition-colors group-hover/release:text-accent">
+                    {item.label}
+                  </span>
+                  {item.tag && (
+                    <span class="shrink-0 rounded-full bg-muted px-2 py-0.5 font-medium text-[0.65rem] text-muted-foreground">
+                      {item.tag}
+                    </span>
+                  )}
+                  {item.date && (
+                    <time
+                      class="shrink-0 font-mono text-muted-foreground text-xs tabular-nums"
+                      datetime={item.dateTime}
+                    >
+                      {item.date}
+                    </time>
+                  )}
+                </a>
+              </li>
+            ))}
+          </ul>
+        </section>
+      ))}
+    </div>
+  )
+}

package/src/components/content/CodeBlock.astro

@@ -9,14 +9,16 @@
 // The theme's code styles are scoped to `.prose`, so the output is wrapped in a
 // `.prose` container (`max-w-none` so it fills its own column rather than the
 // prose reading measure); that's what makes the light/dark swap work on a bare
-// page without the manual `[data-theme]` CSS it would otherwise need.
+// page without the manual `[data-theme]` CSS it would otherwise need. Without
+// `code`, the children render as written: a fenced block wrapped in
+// `<CodeBlock>` (Fern's and Mintlify's spelling) is already highlighted.
 import data from "blume:data";
 
-import { highlightCode } from "../../markdown/index.ts";
+import { codeBlockHtml } from "./code-block.ts";
 
 interface Props {
-  /** The source to highlight. */
-  code: string;
+  /** The source to highlight; without it, the children render instead. */
+  code?: string;
   /** Shiki language id (default `txt`); an unknown one renders plain. */
   lang?: string;
   /** Show the brand language icon in the header (default on, like fences). */
@@ -25,12 +27,7 @@ interface Props {
   title?: string;
 }
 
-const { code, lang = "txt", icons, title } = Astro.props;
-const html = await highlightCode(code.replace(/\n+$/u, ""), lang, {
-  icons,
-  themes: data.config.codeThemes,
-  title,
-});
+const html = await codeBlockHtml(Astro.props, data.config.codeThemes);
 ---
 
-<div class="prose max-w-none"><Fragment set:html={html} /></div>
+{html === null ? <slot /> : <div class="prose max-w-none"><Fragment set:html={html} /></div>}

package/src/components/content/Tabs.astro

@@ -110,6 +110,8 @@ const { content: strings } = contentStrings(data, Astro.currentLocale);
 </blume-tabs>
 
 <script>
+  import { languageLabel } from "../code-language.ts";
+
   const TRIGGER_CLASS =
     "-mb-px inline-flex shrink-0 cursor-pointer items-center gap-1.5 border-transparent border-b-2 bg-transparent px-1 py-2.5 font-medium text-muted-foreground text-xs transition-colors hover:text-foreground aria-[selected=true]:border-accent aria-[selected=true]:text-foreground";
   const SELECT_CLASS =
@@ -120,9 +122,20 @@ const { content: strings } = contentStrings(data, Astro.currentLocale);
   // in several <Tabs> instances on one page.
   let instanceCount = 0;
 
-  // An untitled panel is numbered with its group's localized `Tab {n}`.
+  // An untitled code block (a CodeGroup fence) is named by its language, read
+  // from the fence's own id: the docs layout moves that to
+  // `data-blume-language` when it relabels `data-language` for the header.
+  const codeLanguage = (panel: HTMLElement) => {
+    const language = panel.matches("pre")
+      ? (panel.dataset.blumeLanguage ?? panel.dataset.language)
+      : undefined;
+    return language ? languageLabel(language) : undefined;
+  };
+
+  // Any other untitled panel is numbered with its group's localized `Tab {n}`.
   const panelTitle = (panel: HTMLElement, index: number) =>
     panel.dataset.title ??
+    codeLanguage(panel) ??
     (
       panel.closest<HTMLElement>("blume-tabs")?.dataset.i18nTab ?? "Tab {n}"
     ).replace("{n}", String(index + 1));
@@ -160,7 +173,8 @@ const { content: strings } = contentStrings(data, Astro.currentLocale);
       ).filter((panel) => panel.closest("blume-tabs") === this);
       // CodeGroup passes raw code fences instead of <Tab> elements, so adopt
       // the content wrapper's direct code blocks as panels. The tab label comes
-      // from each block's title (the text after the language in the fence).
+      // from each block's title (the text after the language in the fence),
+      // or from its language when it has none.
       // A ts2js fence arrives as its own TypeScript/JavaScript group; it is
       // one panel too, labeled by the fence title both of its blocks carry.
       if (panels.length === 0) {

package/src/components/content/YouTube.astro

@@ -1,5 +1,5 @@
 ---
-import { parseYouTubeId, youtubeEmbedUrl } from "./youtube.ts";
+import { youtubeEmbedSrc } from "./youtube.ts";
 
 interface Props {
   /** A YouTube video id (e.g. `dQw4w9WgXcQ`). */
@@ -8,14 +8,16 @@ interface Props {
   start?: number;
   /** Accessible title for the embedded player. */
   title?: string;
-  /** A full YouTube URL to extract the id from, as an alternative to `id`. */
+  /**
+   * A full YouTube URL to extract the id from, as an alternative to `id`; a
+   * playlist URL embeds the playlist.
+   */
   url?: string;
 }
 
 const { id, start, title = "YouTube video player", url } = Astro.props;
 
-const videoId = parseYouTubeId(id ?? url ?? "");
-const src = videoId ? youtubeEmbedUrl(videoId, { start }) : null;
+const src = youtubeEmbedSrc(id ?? url ?? "", { start });
 ---
 
 {

package/src/components/content/code-block.ts

@@ -0,0 +1,33 @@
+/**
+ * The highlighting half of the `<CodeBlock>` content component, kept in a
+ * sibling `.ts` (like `badge-color.ts`) so it is unit-testable.
+ */
+import { highlightCode } from "../../markdown/index.ts";
+import type { CodeThemes } from "../../markdown/index.ts";
+
+/** The props `<CodeBlock>` highlights from. */
+export interface CodeBlockSource {
+  code?: string;
+  icons?: boolean;
+  lang?: string;
+  title?: string;
+}
+
+/**
+ * The highlighted HTML for a `<CodeBlock>`, or null when it has no `code`.
+ * Fern and Mintlify wrap a fenced block in `<CodeBlock>…</CodeBlock>`; the
+ * fence inside is already highlighted by the Markdown pipeline, so a
+ * `CodeBlock` without `code` renders its children as written rather than
+ * failing the page on the missing string.
+ */
+export const codeBlockHtml = async (
+  { code, icons, lang = "txt", title }: CodeBlockSource,
+  themes?: CodeThemes
+): Promise<string | null> =>
+  code === undefined
+    ? null
+    : await highlightCode(code.replace(/\n+$/u, ""), lang, {
+        icons,
+        themes,
+        title,
+      });

package/src/components/content/content-strings.ts

@@ -9,7 +9,10 @@ export interface ContentStringsData {
 }
 
 /** The UI string groups a content component's chrome reads. */
-export type ContentStrings = Pick<UIStrings, "actions" | "content">;
+export type ContentStrings = Pick<
+  UIStrings,
+  "actions" | "changelog" | "content"
+>;
 
 /**
  * Labels for a component rendered inside page content (MDX), which gets no
@@ -29,6 +32,7 @@ export const contentStrings = (
       : data.ui;
   return {
     actions: { ...EN_UI.actions, ...dictionary.actions },
+    changelog: { ...EN_UI.changelog, ...dictionary.changelog },
     content: { ...EN_UI.content, ...dictionary.content },
   };
 };

package/src/components/content/inline-markdown.ts

@@ -29,20 +29,47 @@ export const rawHtmlAsTextPlugin = defineMdastPlugin({
  * `<p>a</p>\n<p>b</p>` would "unwrap" to `a</p>\n<p>b` — unbalanced HTML
  * injected via `set:html`.
  */
+const SINGLE_PARAGRAPH = /^<p>(?<content>(?:(?!<\/p>)[\s\S])*)<\/p>$/u;
+
 export const unwrapParagraph = (html: string): string => {
   const trimmed = html.trim();
-  const match = trimmed.match(/^<p>(?<content>(?:(?!<\/p>)[\s\S])*)<\/p>$/u);
-  return match?.groups?.content ?? trimmed;
+  return SINGLE_PARAGRAPH.exec(trimmed)?.groups?.content ?? trimmed;
 };
 
-/**
- * Render a short Markdown text prop to inline HTML, its raw HTML shown as
- * text (see {@link rawHtmlAsTextPlugin}) and a single paragraph unwrapped.
- */
-export const renderInlineMarkdown = async (value: string): Promise<string> => {
+/** Render Markdown to HTML, its raw HTML shown as text. */
+const renderMarkdown = async (value: string): Promise<string> => {
   const processor = await createSatteriMarkdownProcessor({
     mdastPlugins: [rawHtmlAsTextPlugin],
   });
   const rendered = await processor.render(value);
-  return unwrapParagraph(rendered.code);
+  return rendered.code;
+};
+
+/**
+ * Render a short Markdown text prop to inline HTML, its raw HTML shown as
+ * text (see {@link rawHtmlAsTextPlugin}) and a single paragraph unwrapped.
+ */
+export const renderInlineMarkdown = async (value: string): Promise<string> =>
+  unwrapParagraph(await renderMarkdown(value));
+
+// What inline Markdown a title can hold starts with: a backslash escape, a
+// code span, emphasis or strikethrough, or a link.
+const INLINE_SYNTAX = /[\\`*_~[]/u;
+
+/**
+ * A title prop (a callout's, an accordion item's) as inline HTML, with its
+ * Markdown rendered — `` `code` ``, `**bold**`, `[links](/x)` — and its raw
+ * HTML shown as text. Undefined when the title renders as written instead:
+ * when it holds none of that syntax, so a plain title keeps the exact text it
+ * always rendered, and when it doesn't render as one paragraph (`1. Install`
+ * is no list).
+ */
+export const renderInlineTitle = async (
+  value: string
+): Promise<string | undefined> => {
+  if (!INLINE_SYNTAX.test(value)) {
+    return undefined;
+  }
+  const html = await renderMarkdown(value);
+  return SINGLE_PARAGRAPH.exec(html.trim())?.groups?.content;
 };

package/src/components/content/youtube.ts

@@ -8,9 +8,15 @@
 const BARE_ID = /^[\w-]{11}$/u;
 
 // Pull the id out of any common YouTube URL: youtu.be/<id>, watch?v=<id>,
-// /embed/<id>, /shorts/<id>, /live/<id>.
+// /embed/<id>, /shorts/<id>, /live/<id>. A playlist embed's
+// `/embed/videoseries` is 11 characters too, but it names no video.
 const URL_ID =
-  /(?:youtu\.be\/|\/embed\/|\/shorts\/|\/live\/|[?&]v=)(?<id>[\w-]{11})/u;
+  /(?:youtu\.be\/|\/embed\/(?!videoseries\b)|\/shorts\/|\/live\/|[?&]v=)(?<id>[\w-]{11})/u;
+
+// A playlist URL: the embed form, `/embed/videoseries?list=<id>`, or the
+// playlist page, `/playlist?list=<id>`.
+const PLAYLIST =
+  /\/(?:embed\/videoseries|playlist)\?(?:[^#]*&)?list=(?<list>[\w-]+)/u;
 
 /**
  * Resolve a YouTube video id from either a bare id or a full URL. Returns `null`
@@ -28,6 +34,18 @@ export const parseYouTubeId = (input: string): string | null => {
   return URL_ID.exec(value)?.groups?.id ?? null;
 };
 
+/**
+ * The playlist id of a YouTube playlist URL (`/embed/videoseries?list=…` or
+ * `/playlist?list=…`), or `null` for anything else — a video URL that also
+ * carries a `list` (`watch?v=…&list=…`) is that video.
+ */
+export const parseYouTubePlaylist = (input: string): string | null =>
+  PLAYLIST.exec(input.trim())?.groups?.list ?? null;
+
+/** The query a `start` time adds to an embed URL, or nothing. */
+const startParam = (start: number | undefined): Record<string, string> =>
+  start && start > 0 ? { start: String(Math.floor(start)) } : {};
+
 /**
  * Build a privacy-enhanced (`youtube-nocookie.com`) embed URL, optionally
  * starting at `start` seconds.
@@ -37,10 +55,34 @@ export const youtubeEmbedUrl = (
   options: { start?: number } = {}
 ): string => {
   const base = `https://www.youtube-nocookie.com/embed/${id}`;
-  const { start } = options;
-  if (start && start > 0) {
-    const params = new URLSearchParams({ start: String(Math.floor(start)) });
-    return `${base}?${params.toString()}`;
+  const params = new URLSearchParams(startParam(options.start));
+  return params.size > 0 ? `${base}?${params.toString()}` : base;
+};
+
+/**
+ * The privacy-enhanced embed URL for a playlist, optionally starting its
+ * first video at `start` seconds.
+ */
+export const youtubePlaylistEmbedUrl = (
+  list: string,
+  options: { start?: number } = {}
+): string => {
+  const params = new URLSearchParams({ list, ...startParam(options.start) });
+  return `https://www.youtube-nocookie.com/embed/videoseries?${params.toString()}`;
+};
+
+/**
+ * The embed URL for a `<YouTube>`'s `id` or `url`: a video, else a playlist,
+ * else `null` when the input names neither.
+ */
+export const youtubeEmbedSrc = (
+  input: string,
+  options: { start?: number } = {}
+): string | null => {
+  const id = parseYouTubeId(input);
+  if (id) {
+    return youtubeEmbedUrl(id, options);
   }
-  return base;
+  const list = parseYouTubePlaylist(input);
+  return list ? youtubePlaylistEmbedUrl(list, options) : null;
 };

package/src/components/layout/Analytics.astro

@@ -21,7 +21,11 @@ interface Props {
 }
 
 const { analytics } = Astro.props;
-const nodes = analyticsHead(import.meta.env.PROD ? (analytics ?? []) : []);
+// A `script()` src in `public/` is served under the deployment base.
+const nodes = analyticsHead(
+  import.meta.env.PROD ? (analytics ?? []) : [],
+  import.meta.env.BASE_URL
+);
 const held = data.config.consent
   ? { "data-blume-consent": "analytics", type: "text/plain" }
   : {};

package/src/components/layout/NavTree.astro

@@ -8,7 +8,7 @@ import { withBase, withMountedBase } from "../islands/base-path.ts";
 import Self from "./NavTree.astro";
 import NavTreeCache from "./NavTreeCache.astro";
 import NavTreeScript from "./NavTreeScript.astro";
-import { isGroupRowCurrent } from "./nav-utils.ts";
+import { groupStartsOpen, isGroupRowCurrent } from "./nav-utils.ts";
 
 interface PagePanel {
   id: string;
@@ -388,8 +388,13 @@ const initialId =
         if (display === "group") {
           const active = hasActivePage(item);
           // Default every group closed; open only those on the active path (so
-          // the current page's ancestors stay expanded) or forced open via meta.
-          const open = active || item.collapsed === false;
+          // the current page's ancestors stay expanded), forced open via meta,
+          // or alone at the top of the sidebar.
+          const open = groupStartsOpen(
+            item,
+            active,
+            depth === 0 && items.length === 1
+          );
           return (
             <li class={spacing}>
               <details open={open}>