blume 0.6.0 → 0.6.1

package/dist/types/core/config.d.ts

@@ -1,8 +1,131 @@
-import type { BlumeConfig, ResolvedConfig } from "./schema.ts";
+import type { BlumeConfig } from "./config-input.ts";
+import type { ResolvedConfig } from "./schema.ts";
 import type { Diagnostic } from "./types.ts";
 /**
- * Identity helper for authoring `blume.config.ts`. Exists for type inference
- * and a stable future home for plugin hooks; it does not transform input.
+ * Define a Blume site's configuration with full type-checking and editor
+ * autocomplete. Place the call in `blume.config.ts` at your project root and
+ * `export default` the result:
+ *
+ * ```ts
+ * import { defineConfig } from "blume";
+ *
+ * export default defineConfig({
+ *   title: "Acme Docs",
+ *   description: "Everything you need to build with Acme.",
+ * });
+ * ```
+ *
+ * Every field is optional — an empty `defineConfig({})` produces a working
+ * site from the Markdown/MDX in your `docs/` directory. Configure only what you
+ * want to change; sensible defaults fill in the rest.
+ *
+ * This is an identity helper: it returns its input unchanged and exists purely
+ * for type inference (and as a stable home for future plugin hooks). The object
+ * is validated against the Blume schema when the CLI loads it.
+ *
+ * ## Top-level fields
+ *
+ * **Site identity**
+ * - `title` — site title, shown in the header, `<title>`, and OG images.
+ *   Defaults to `"Documentation"`.
+ * - `description` — default meta description, used where a page sets none.
+ * - `logo` — brand mark. A string is an image path/URL; the object form splits
+ *   an `image` mark from wordmark `text` and can override the brand `href`.
+ * - `banner` — site-wide announcement bar; a string, or `{ content, link,
+ *   dismissible }`.
+ *
+ * **Content & navigation**
+ * - `content` — where content lives (`root`, defaults to `docs`) and pluggable
+ *   `sources` (filesystem, remote MDX, GitHub Releases, Sanity, Notion, or a
+ *   custom `ContentSource`). Omit `sources` and the top-level `root` becomes one
+ *   implicit filesystem source.
+ * - `navigation` — sidebar, header `tabs`, `selectors` (version/language/product
+ *   switchers), pinned `featured` links, and the `repo` link toggle. Omit
+ *   `sidebar` to generate it from the content tree.
+ * - `redirects` — `{ from, to, status }` rules (301 by default).
+ * - `github` — `{ owner, repo, branch, dir }`, powering "Edit this page" links
+ *   and the header repo link.
+ *
+ * **Appearance**
+ * - `theme` — `accent` color, `fonts` (curated Google Font slugs), `radius`,
+ *   `mode` (`system`/`light`/`dark`), `background`, and `strict` token mode.
+ * - `markdown` — `code` (language icons, inline highlighting, line wrap),
+ *   `headingAnchors`, `imageZoom`, and opt-in KaTeX `math`.
+ * - `toc` — on-page table of contents; `true`/`false` or a heading-level range.
+ * - `lastModified` — "Last updated" stamps from `git` history or frontmatter.
+ * - `feedback` — the per-page "Was this helpful?" widget (on by default).
+ * - `export` — reader-facing PDF/EPUB export actions (off by default).
+ *
+ * **Reference docs**
+ * - `openapi` — native OpenAPI reference: one real page per operation, woven
+ *   into the sidebar and search. Point `sources`/`spec` at your spec.
+ * - `asyncapi` — AsyncAPI reference via the embedded Scalar renderer.
+ *
+ * **Search & AI**
+ * - `search` — search backend `provider` (`orama` by default; `pagefind`,
+ *   `algolia`, `typesense`, `orama-cloud`, `mixedbread`, or `none`) plus its
+ *   credential block.
+ * - `ai` — `ask` (the Ask AI chat endpoint and its provider/model) and `llmsTxt`
+ *   (emit `llms.txt`).
+ * - `mcp` — expose the docs as an MCP server for connecting agents.
+ *
+ * **SEO, feeds & analytics**
+ * - `seo` — `og` images, `sitemap`, `robots`, `rss` feeds, `structuredData`
+ *   JSON-LD, `agentReadability`, and robots `contentSignals`.
+ * - `analytics` — PostHog, Vercel, or arbitrary `scripts` (Plausible, Fathom,
+ *   GA, …).
+ *
+ * **Deployment & i18n**
+ * - `deployment` — `site` URL (needed for absolute links, sitemaps, and OG),
+ *   `adapter` (`vercel`/`node`/`netlify`/`cloudflare`), `output`
+ *   (`static`/`server`), and `base` path. Auto-detected on Vercel/Netlify/
+ *   Cloudflare from the platform env.
+ * - `i18n` — opt-in multi-locale: `locales`, `defaultLocale`, `parser`
+ *   (`dir` vs filename `dot` suffix), and per-locale UI overrides.
+ *
+ * - `examples` — where `<Component path>` previews resolve their source from
+ *   (defaults to `examples/`; supports a glob for colocated registries).
+ *
+ * @example Zero-config — just render the Markdown under `docs/`.
+ * ```ts
+ * export default defineConfig({});
+ * ```
+ *
+ * @example A production docs site with theming, search, and deployment.
+ * ```ts
+ * export default defineConfig({
+ *   title: "Acme Docs",
+ *   description: "Build faster with Acme.",
+ *   logo: { image: "/logo.svg", text: "Acme" },
+ *   github: { owner: "acme", repo: "acme" },
+ *   theme: { accent: "violet", fonts: { body: "inter" }, radius: "lg" },
+ *   navigation: {
+ *     tabs: [
+ *       { label: "Guides", path: "/guides" },
+ *       { label: "API", path: "/api" },
+ *     ],
+ *   },
+ *   search: { provider: "orama" },
+ *   deployment: { site: "https://docs.acme.com", adapter: "vercel" },
+ * });
+ * ```
+ *
+ * @example An OpenAPI reference with the Ask AI assistant enabled.
+ * ```ts
+ * export default defineConfig({
+ *   title: "Acme API",
+ *   openapi: {
+ *     enabled: true,
+ *     route: "/reference",
+ *     sources: [{ label: "Core", spec: "./openapi.json" }],
+ *   },
+ *   ai: { ask: { enabled: true }, llmsTxt: true },
+ * });
+ * ```
+ *
+ * @param config - The site configuration. All fields are optional.
+ * @returns The same config object, typed for inference.
+ * @see https://useblume.dev/docs for the full configuration reference.
  */
 export declare const defineConfig: (config: BlumeConfig) => BlumeConfig;
 /** Result of loading + validating a project config. */

package/dist/types/core/schema.d.ts

@@ -1708,12 +1708,6 @@ export declare const blumeConfigSchema: z.ZodObject<{
              * …). On by default; recognized languages only.
              */
             icons: z.ZodDefault<z.ZodBoolean>;
-            /**
-             * Syntax-highlight inline `` `code{:lang}` `` snippets. Off by default — most
-             * inline code (flags, file names) reads better plain; opt a snippet in with
-             * a trailing `{:lang}` marker.
-             */
-            inline: z.ZodDefault<z.ZodBoolean>;
             /**
              * Wrap long lines instead of scrolling horizontally. Off by default, so
              * code keeps its original line breaks and overflows into a scroll area.
@@ -1721,11 +1715,9 @@ export declare const blumeConfigSchema: z.ZodObject<{
             wrap: z.ZodDefault<z.ZodBoolean>;
         }, "strict", z.ZodTypeAny, {
             icons: boolean;
-            inline: boolean;
             wrap: boolean;
         }, {
             icons?: boolean | undefined;
-            inline?: boolean | undefined;
             wrap?: boolean | undefined;
         }>>;
         codeBlocks: z.ZodDefault<z.ZodObject<{
@@ -1761,15 +1753,9 @@ export declare const blumeConfigSchema: z.ZodObject<{
          * opt a single image out with `data-no-zoom`.
          */
         imageZoom: z.ZodDefault<z.ZodBoolean>;
-        /**
-         * Enable LaTeX math (`$…$` inline, `$$…$$` block) rendered with KaTeX.
-         * Off by default since `$` is common in prose, shell, and code. MDX only.
-         */
-        math: z.ZodDefault<z.ZodBoolean>;
     }, "strict", z.ZodTypeAny, {
         code: {
             icons: boolean;
-            inline: boolean;
             wrap: boolean;
         };
         codeBlocks: {
@@ -1780,11 +1766,9 @@ export declare const blumeConfigSchema: z.ZodObject<{
         };
         headingAnchors: boolean;
         imageZoom: boolean;
-        math: boolean;
     }, {
         code?: {
             icons?: boolean | undefined;
-            inline?: boolean | undefined;
             wrap?: boolean | undefined;
         } | undefined;
         codeBlocks?: {
@@ -1795,7 +1779,6 @@ export declare const blumeConfigSchema: z.ZodObject<{
         } | undefined;
         headingAnchors?: boolean | undefined;
         imageZoom?: boolean | undefined;
-        math?: boolean | undefined;
     }>>;
     mcp: z.ZodDefault<z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
@@ -2664,7 +2647,6 @@ export declare const blumeConfigSchema: z.ZodObject<{
     markdown: {
         code: {
             icons: boolean;
-            inline: boolean;
             wrap: boolean;
         };
         codeBlocks: {
@@ -2675,7 +2657,6 @@ export declare const blumeConfigSchema: z.ZodObject<{
         };
         headingAnchors: boolean;
         imageZoom: boolean;
-        math: boolean;
     };
     mcp: {
         enabled: boolean;
@@ -3022,7 +3003,6 @@ export declare const blumeConfigSchema: z.ZodObject<{
     markdown?: {
         code?: {
             icons?: boolean | undefined;
-            inline?: boolean | undefined;
             wrap?: boolean | undefined;
         } | undefined;
         codeBlocks?: {
@@ -3033,7 +3013,6 @@ export declare const blumeConfigSchema: z.ZodObject<{
         } | undefined;
         headingAnchors?: boolean | undefined;
         imageZoom?: boolean | undefined;
-        math?: boolean | undefined;
     } | undefined;
     mcp?: {
         name?: string | undefined;
@@ -3102,8 +3081,12 @@ export type ResolvedConfig = z.infer<typeof blumeConfigSchema>;
 export type ResolvedI18nConfig = z.infer<typeof i18nConfigSchema>;
 /** A configured locale with display metadata. */
 export type LocaleConfig = z.infer<typeof localeSchema>;
-/** User-authored config: the shape accepted by `defineConfig`. */
-export type BlumeConfig = z.input<typeof blumeConfigSchema>;
+/**
+ * User-authored config, straight off the schema. The public, hand-documented
+ * authoring type is `BlumeConfig` in `./config-input.ts`, which a compile-time
+ * guard keeps structurally identical to this.
+ */
+export type BlumeConfigInput = z.input<typeof blumeConfigSchema>;
 /** A configured search backend. */
 export type SearchProvider = (typeof searchProviders)[number];
 /** Resolved robots.txt `Content-Signal` preferences (`null` when disabled). */

package/dist/types/index.d.ts

@@ -5,6 +5,7 @@ export type { ComponentOverride, ComponentOverrides, IslandDescriptor, } from ".
 export { defineMeta } from "./core/define-meta.ts";
 export type { FolderMetaDefinition, FolderMetaFactory, } from "./core/define-meta.ts";
 export type { UIStrings } from "./core/i18n-ui.ts";
-export type { BlumeConfig, FolderMeta, HydrationMode, ResolvedConfig, } from "./core/schema.ts";
+export type { BlumeConfig } from "./core/config-input.ts";
+export type { FolderMeta, HydrationMode, ResolvedConfig, } from "./core/schema.ts";
 export type { Diagnostic, Heading, NavNode, Navigation, NavTab, PageRecord, } from "./core/types.ts";
 export { getBlumeVersion } from "./core/version.ts";

package/docs/advanced/changelog.mdx

@@ -53,14 +53,22 @@ The optional `changelog` object adds richer metadata for the timeline and feed:
 
 ## The timeline page
 
-Once you have at least one `type: changelog` entry, Blume generates a **`/changelog`** page automatically. Each entry renders newest-first with its date, label, and `category` tag in a left rail beside its content:
+Once you have at least one `type: changelog` entry, Blume generates a **`/changelog`** page automatically. It renders as a focused, full-width timeline — no sidebar or table of contents — with each entry newest-first, showing its date, label, and `category` tag in a left rail beside its content:
 
-- The entry **title** becomes its label — or `v{version}` when there's no title.
+- The entry **title** becomes its label — or `v{version}` when there's no title. It links to that entry's own page, so a release is both a line in the timeline and a shareable permalink.
 - The `category` renders as a tag next to the date.
 - Drafts and `sidebar.hidden` entries are skipped.
 
 The page appears only when nothing already occupies the `/changelog` route. To replace it with your own design, add a [custom page](/docs/advanced/custom-pages) at `pages/changelog.astro` — it takes over and Blume stops generating the default timeline.
 
+### Grouped by major version
+
+When your versions follow [semver](https://semver.org) and span more than one major, Blume paginates the timeline by major version. Only the newest major line is shown, with a **Show N.x releases** button at the bottom that reveals the next-oldest major one click at a time:
+
+- Detection is automatic — no configuration. It kicks in only when every listed release parses as `major.minor.patch` and there is more than one major; otherwise the timeline stays flat.
+- It tolerates the scoped tags monorepos publish, so `pkg@2.0.0` groups under `2.x` and `pkg@1.4.0` under `1.x`.
+- It's progressive enhancement: every release is still in the page's HTML (and its RSS feed and search index), so readers without JavaScript — and crawlers — see the complete history. The button only collapses older majors once the page hydrates.
+
 ## From GitHub Releases
 
 Rather than authoring entries by hand, point the built-in [`github-releases` source](/docs/content/sources#github-releases) at a repo and every release becomes a `type: changelog` entry — the same timeline and feed, fed straight from the releases you already publish:

package/docs/configuration/index.mdx

@@ -49,11 +49,9 @@ export default defineConfig({
   // Markdown features
   markdown: {
     imageZoom: true,
-    math: false,
     code: {
       icons: true, // language icon in the code-block header
       wrap: false, // wrap long lines instead of scrolling
-      inline: false, // highlight inline `code{:lang}` snippets
     },
   },
 

package/docs/content/syntax.mdx

@@ -139,7 +139,7 @@ export default defineConfig({
 ```
 ````
 
-Inline code can be highlighted too: add a `{:lang}` marker inside a backtick span and it's colored like a tiny code block — `useState(){:js}` or `T extends object{:ts}`. Turn it on with `markdown: { code: { inline: true } }`.
+Inline code can be highlighted too: add a `{:lang}` marker inside a backtick span and it's colored like a tiny code block — `useState(){:js}` or `T extends object{:ts}`. It only kicks in when you add the marker, so plain inline code stays untouched — nothing to switch on.
 
 ### Line numbers
 
@@ -372,24 +372,20 @@ The names `caution`, `error`, `important`, and `warn` are accepted as aliases fo
 
 ## Math
 
-Render LaTeX with KaTeX for formulas in prose or as centered blocks — useful for math-heavy or scientific docs. Inline math goes in `$…$`; block math in `$$…$$`.
-
-The Pythagorean theorem is $a^2 + b^2 = c^2$.
+Render LaTeX with KaTeX as centered blocks — useful for math-heavy or scientific docs. Wrap a formula in `$$…$$`:
 
 $$
 \int_0^\infty e^{-x^2}\,dx = \frac{\sqrt{\pi}}{2}
 $$
 
 ```md
-The Pythagorean theorem is $a^2 + b^2 = c^2$.
-
 $$
-\int_0^\infty e^{-x^2}\,dx = \frac{\sqrt{\pi}}{2}
+a^2 + b^2 = c^2
 $$
 ```
 
 :::note
-Math is opt-in because `$` is common in prose and code. Enable it with `markdown: { math: true }` in `blume.config.ts`.
+Math is block-only and on automatically — write `$$…$$` and it renders; write none and KaTeX's stylesheet never ships. There's no inline `$…$` math: a lone `$` (currency, shell variables, code) is always left as literal text, so there's no delimiter to escape and no setting to toggle. Math is an MDX-only feature.
 :::
 
 ## Smart punctuation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",

package/src/astro/generate.ts

@@ -330,6 +330,26 @@ export const detectNeedsReact = async (root: string): Promise<boolean> => {
   return matches.length > 0;
 };
 
+/**
+ * Detect whether the project authors block math (`$$…$$`) in any `.mdx`. Drives
+ * whether the generated runtime imports the `<Math>` component and KaTeX's
+ * stylesheet, so a math-free site ships no KaTeX CSS. Math parsing itself is
+ * always on but block-only, so a literal `$$` in source is a necessary
+ * condition — no false negatives. A stray `$$` (e.g. inside a code fence) merely
+ * over-includes the idempotent import, which is harmless.
+ */
+export const detectUsesMath = async (root: string): Promise<boolean> => {
+  const files = await glob(["**/*.mdx"], {
+    cwd: root,
+    ignore: ["**/node_modules/**", "**/.blume/**", "**/dist/**"],
+    onlyFiles: true,
+  });
+  const contents = await Promise.all(
+    files.map((file) => readOptional(join(root, file)))
+  );
+  return contents.some((content) => content.includes("$$"));
+};
+
 const writeIfChanged = async (
   path: string,
   content: string
@@ -933,16 +953,21 @@ export const generateRuntime = async (
   const askEnabled = config.ai.ask?.enabled ?? false;
   const exportPdf = config.export.pdf;
   const exportEpub = config.export.epub;
-  const [pages, detectedReact, userTheme, islandDiscovery, exampleDiscovery] =
-    await Promise.all([
-      context.pagesRoot
-        ? discoverPages(context.pagesRoot)
-        : Promise.resolve([]),
-      detectNeedsReact(context.root),
-      readOptional(context.themeFile),
-      discoverIslands(context.root),
-      discoverExamples(context.root, config.examples),
-    ]);
+  const [
+    pages,
+    detectedReact,
+    usesMath,
+    userTheme,
+    islandDiscovery,
+    exampleDiscovery,
+  ] = await Promise.all([
+    context.pagesRoot ? discoverPages(context.pagesRoot) : Promise.resolve([]),
+    detectNeedsReact(context.root),
+    detectUsesMath(context.root),
+    readOptional(context.themeFile),
+    discoverIslands(context.root),
+    discoverExamples(context.root, config.examples),
+  ]);
   // Statically analyze `components.ts` overrides (never executed): drives the
   // `islands` group, hydration on layout/mdx overrides, string-path resolution,
   // and the "framework component with no client mode" diagnostic.
@@ -1028,7 +1053,7 @@ export const generateRuntime = async (
         askEnabled,
         exportEpub,
         exportPdf,
-        mathEnabled: config.markdown.math,
+        mathEnabled: usesMath,
         needsReact,
       })
     ),

package/src/astro/templates.ts

@@ -300,8 +300,6 @@ export const astroConfigTemplate = (options: {
   const integrations = [
     `mdx({ processor: blumeMdxProcessor(${JSON.stringify({
       headingAnchors: config.markdown.headingAnchors,
-      inline: config.markdown.code.inline,
-      math: config.markdown.math,
     })}) })`,
   ];
   if (needsReact) {
@@ -335,7 +333,6 @@ export default defineConfig({
   markdown: {
     processor: blumeMarkdownProcessor(${JSON.stringify({
       headingAnchors: config.markdown.headingAnchors,
-      inline: config.markdown.code.inline,
     })}),
     shikiConfig: {
       themes: {
@@ -1278,6 +1275,20 @@ const slugify = (text) =>
   text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") ||
   "update";
 
+// The major of a version's embedded semver (\`1.2.3\` -> 1, \`pkg@2.0.0\` -> 2), or
+// null when there is no full major.minor.patch to key on. Drives the changelog's
+// group-by-major pagination, so it tolerates the scoped tags monorepos publish.
+const majorVersion = (version) => {
+  const match = /(\\d+)\\.\\d+\\.\\d+/.exec(String(version ?? ""));
+  return match ? Number(match[1]) : null;
+};
+
+// Map each entry to its own generated page so the timeline heading can deep-link
+// to it. The collection entry id matches the route manifest's \`entryId\`.
+const routeByEntry = new Map(
+  data.routes.map((route) => [route.entryId, route.path])
+);
+
 const changelogEntries = [
   ...(await getCollection("docs")),${stagedSpread}
 ]
@@ -1299,8 +1310,10 @@ const items = await Promise.all(
     return {
       Content: (await render(entry)).Content,
       date: formatDate(entryDate(entry)),
+      href: routeByEntry.get(entry.id) ?? null,
       id: slugify(label),
       label,
+      major: majorVersion(entry.data.changelog?.version),
       tags: entry.data.changelog?.category
         ? [entry.data.changelog.category]
         : [],
@@ -1308,6 +1321,19 @@ const items = await Promise.all(
   })
 );
 
+// A changelog is semver-paginated only when every visible release parses as
+// semver and they span more than one major line. Older majors then collapse
+// into groups the reader reveals one at a time; otherwise the timeline is flat.
+const majors = items.every((item) => item.major !== null)
+  ? [...new Set(items.map((item) => item.major))].toSorted((a, b) => b - a)
+  : [];
+const paginate = majors.length > 1;
+const majorGroups = majors.map((major) => ({
+  items: items.filter((item) => item.major === major),
+  label: major + ".x",
+  major,
+}));
+
 const headings = items.map((item) => ({
   depth: 2,
   slug: item.id,
@@ -1339,6 +1365,7 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   }}
   headings={headings}
   toc={data.config.toc}
+  contentLayout="bare"
   themeMode={data.config.theme.mode}
   fontCssVars={data.fontCssVars}
   searchEnabled={data.config.search.enabled}
@@ -1357,16 +1384,50 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   {
     items.length === 0 ? (
       <p>No changelog entries yet.</p>
+    ) : paginate ? (
+      <blume-changelog class="not-prose mt-8 block">
+        {majorGroups[0].items.map(({ Content, href, id, label, date, tags }) => (
+          <Update description={date} href={href} id={id} label={label} tags={tags}>
+            <Content />
+          </Update>
+        ))}
+        {majorGroups.slice(1).map((group) => (
+          <section
+            aria-label={group.label + " releases"}
+            data-changelog-label={group.label}
+            data-changelog-major={group.major}
+          >
+            {group.items.map(({ Content, href, id, label, date, tags }) => (
+              <Update description={date} href={href} id={id} label={label} tags={tags}>
+                <Content />
+              </Update>
+            ))}
+          </section>
+        ))}
+        <div class="mt-10 flex justify-center">
+          <button
+            class="inline-flex items-center gap-2 rounded-full border border-border bg-background px-4 py-2 font-medium text-muted-foreground text-sm transition-colors hover:bg-muted hover:text-foreground"
+            data-changelog-more
+            hidden
+            type="button"
+          >
+            Show older releases
+          </button>
+        </div>
+      </blume-changelog>
     ) : (
       <div class="not-prose mt-8">
-        {items.map(({ Content, id, label, date, tags }) => (
-          <Update description={date} id={id} label={label} tags={tags}>
+        {items.map(({ Content, href, id, label, date, tags }) => (
+          <Update description={date} href={href} id={id} label={label} tags={tags}>
             <Content />
           </Update>
         ))}
       </div>
     )
   }
+  <script>
+    import "blume/components/content/changelog-element.ts";
+  </script>
 </LayoutComponent>
 `;
 };

package/src/cli/commands/build.ts

@@ -11,6 +11,10 @@ import { ensureGitignore } from "../../core/gitignore.ts";
 import type { BlumeProject } from "../../core/project-graph.ts";
 import type { ResolvedConfig } from "../../core/schema.ts";
 import { serverFeatures } from "../../core/server-features.ts";
+import {
+  deployStaticDir,
+  surfaceAdapterOutput,
+} from "../../deploy/adapter-output.ts";
 import {
   buildNetlifyRedirects,
   buildRedirectManifest,
@@ -365,6 +369,27 @@ export const buildCommand = defineCommand({
       return;
     }
 
-    await publishBuildArtifacts(project, distDir, args);
+    // A server adapter (Vercel/Netlify) writes its deploy bundle relative to the
+    // Astro root — which Blume points at the hidden `.blume` runtime — so the
+    // bundle lands where the deploy platform never looks. Surface it up to the
+    // project root before publishing artifacts into the served static dir.
+    const surfaced = await surfaceAdapterOutput(
+      project.config,
+      project.context
+    );
+    if (surfaced.moved) {
+      logger.success(
+        `Surfaced ${project.config.deployment.adapter} output to ${surfaced.to}`
+      );
+      // The surfaced bundle is a build artifact — keep it out of version control
+      // (Vercel's own CLI ignores `.vercel/` for the same reason).
+      await ensureGitignore(root, [surfaced.ignore]);
+    }
+
+    await publishBuildArtifacts(
+      project,
+      deployStaticDir(project.config, project.context),
+      args
+    );
   },
 });

package/src/components/content/Update.astro

@@ -6,6 +6,8 @@ interface RssMetadata {
 
 interface Props {
   description?: string;
+  /** Link the heading to a dedicated page; falls back to the in-page anchor. */
+  href?: string;
   id?: string;
   label?: string;
   rss?: RssMetadata;
@@ -13,7 +15,15 @@ interface Props {
   title?: string;
 }
 
-const { description, id: providedId, label, rss, tags, title } = Astro.props;
+const {
+  description,
+  href,
+  id: providedId,
+  label,
+  rss,
+  tags,
+  title,
+} = Astro.props;
 const slugify = (text: string): string =>
   text
     .toLowerCase()
@@ -37,7 +47,7 @@ const tagList = Array.isArray(tags) ? tags : tags ? [tags] : [];
   <header class="md:border-border md:border-e md:pe-4">
     <a
       class="font-semibold text-foreground text-sm no-underline hover:text-accent"
-      href={`#${id}`}
+      href={href ?? `#${id}`}
     >
       {updateLabel}
     </a>

package/src/components/content/changelog-element.ts

@@ -0,0 +1,62 @@
+/**
+ * Client behaviour for the `<blume-changelog>` custom element wrapping the
+ * generated changelog timeline when its releases are semver-versioned. The
+ * newest major line stays visible; every older major is collapsed into a group
+ * revealed one major at a time by the "Show N.x releases" button at the bottom.
+ *
+ * Pure progressive enhancement: the server renders every release in document
+ * order, and this element hides the older-major groups on connect — so a no-JS
+ * visitor (or a crawler) still sees the complete history, and the button does
+ * nothing until the script upgrades it.
+ *
+ * Imported for its side effect (registers the element) from the changelog page.
+ */
+
+class BlumeChangelog extends HTMLElement {
+  connectedCallback() {
+    const groups = [
+      ...this.querySelectorAll<HTMLElement>("[data-changelog-major]"),
+    ];
+    const button = this.querySelector<HTMLButtonElement>(
+      "[data-changelog-more]"
+    );
+    if (groups.length === 0 || !button) {
+      return;
+    }
+
+    for (const group of groups) {
+      group.hidden = true;
+      // Focusable only programmatically, so revealing a group can move focus to
+      // it for keyboard and screen-reader users without adding a tab stop.
+      group.tabIndex = -1;
+    }
+
+    let revealed = 0;
+    const sync = () => {
+      const next = groups[revealed];
+      if (next) {
+        button.textContent = `Show ${next.dataset.changelogLabel} releases`;
+        button.hidden = false;
+      } else {
+        button.hidden = true;
+      }
+    };
+
+    button.addEventListener("click", () => {
+      const next = groups[revealed];
+      if (!next) {
+        return;
+      }
+      next.hidden = false;
+      revealed += 1;
+      sync();
+      next.focus();
+    });
+
+    sync();
+  }
+}
+
+if (!customElements.get("blume-changelog")) {
+  customElements.define("blume-changelog", BlumeChangelog);
+}