blume 0.1.4 → 0.2.0

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

@@ -475,6 +475,40 @@ declare const contentSourceSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<
         ref?: string | undefined;
     } | undefined;
     pollInterval?: number | undefined;
+}>, z.ZodObject<{
+    /** Include draft releases (needs a token with repo write access). */
+    drafts: z.ZodOptional<z.ZodBoolean>;
+    /** Cap the number of releases materialized, newest-first. Default 100. */
+    limit: z.ZodOptional<z.ZodNumber>;
+    /** Repository owner (user or org). */
+    owner: z.ZodString;
+    /** Opt-in dev polling interval (seconds); omit to freeze for the session. */
+    pollInterval: z.ZodOptional<z.ZodNumber>;
+    /** Namespaces the source's routes under `/<prefix>/`; e.g. `changelog`. */
+    prefix: z.ZodOptional<z.ZodString>;
+    /** Include prereleases. */
+    prereleases: z.ZodOptional<z.ZodBoolean>;
+    /** Repository name. */
+    repo: z.ZodString;
+    type: z.ZodLiteral<"github-releases">;
+}, "strict", z.ZodTypeAny, {
+    type: "github-releases";
+    owner: string;
+    repo: string;
+    prefix?: string | undefined;
+    pollInterval?: number | undefined;
+    drafts?: boolean | undefined;
+    limit?: number | undefined;
+    prereleases?: boolean | undefined;
+}, {
+    type: "github-releases";
+    owner: string;
+    repo: string;
+    prefix?: string | undefined;
+    pollInterval?: number | undefined;
+    drafts?: boolean | undefined;
+    limit?: number | undefined;
+    prereleases?: boolean | undefined;
 }>, z.ZodObject<{
     /** Sanity API version (a date); default `2024-01-01`. */
     apiVersion: z.ZodOptional<z.ZodString>;
@@ -1119,6 +1153,40 @@ export declare const blumeConfigSchema: z.ZodObject<{
                 ref?: string | undefined;
             } | undefined;
             pollInterval?: number | undefined;
+        }>, z.ZodObject<{
+            /** Include draft releases (needs a token with repo write access). */
+            drafts: z.ZodOptional<z.ZodBoolean>;
+            /** Cap the number of releases materialized, newest-first. Default 100. */
+            limit: z.ZodOptional<z.ZodNumber>;
+            /** Repository owner (user or org). */
+            owner: z.ZodString;
+            /** Opt-in dev polling interval (seconds); omit to freeze for the session. */
+            pollInterval: z.ZodOptional<z.ZodNumber>;
+            /** Namespaces the source's routes under `/<prefix>/`; e.g. `changelog`. */
+            prefix: z.ZodOptional<z.ZodString>;
+            /** Include prereleases. */
+            prereleases: z.ZodOptional<z.ZodBoolean>;
+            /** Repository name. */
+            repo: z.ZodString;
+            type: z.ZodLiteral<"github-releases">;
+        }, "strict", z.ZodTypeAny, {
+            type: "github-releases";
+            owner: string;
+            repo: string;
+            prefix?: string | undefined;
+            pollInterval?: number | undefined;
+            drafts?: boolean | undefined;
+            limit?: number | undefined;
+            prereleases?: boolean | undefined;
+        }, {
+            type: "github-releases";
+            owner: string;
+            repo: string;
+            prefix?: string | undefined;
+            pollInterval?: number | undefined;
+            drafts?: boolean | undefined;
+            limit?: number | undefined;
+            prereleases?: boolean | undefined;
         }>, z.ZodObject<{
             /** Sanity API version (a date); default `2024-01-01`. */
             apiVersion: z.ZodOptional<z.ZodString>;
@@ -1327,6 +1395,15 @@ export declare const blumeConfigSchema: z.ZodObject<{
                 slug?: string | undefined;
             } | undefined;
             publishedValue?: string | undefined;
+        } | {
+            type: "github-releases";
+            owner: string;
+            repo: string;
+            prefix?: string | undefined;
+            pollInterval?: number | undefined;
+            drafts?: boolean | undefined;
+            limit?: number | undefined;
+            prereleases?: boolean | undefined;
         } | {
             type: "mintlify";
             exclude: string[];
@@ -1392,6 +1469,15 @@ export declare const blumeConfigSchema: z.ZodObject<{
                 slug?: string | undefined;
             } | undefined;
             publishedValue?: string | undefined;
+        } | {
+            type: "github-releases";
+            owner: string;
+            repo: string;
+            prefix?: string | undefined;
+            pollInterval?: number | undefined;
+            drafts?: boolean | undefined;
+            limit?: number | undefined;
+            prereleases?: boolean | undefined;
         } | {
             type: "mintlify";
             exclude?: string[] | undefined;
@@ -2606,12 +2692,12 @@ export declare const blumeConfigSchema: z.ZodObject<{
             /** Content types that each get a feed at `/<type>/rss.xml`. */
             types: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
         }, "strict", z.ZodTypeAny, {
-            enabled: boolean;
             limit: number;
+            enabled: boolean;
             types: string[];
         }, {
-            enabled?: boolean | undefined;
             limit?: number | undefined;
+            enabled?: boolean | undefined;
             types?: string[] | undefined;
         }>>;
         /** Generate sitemap.xml (requires deployment.site). */
@@ -2620,8 +2706,8 @@ export declare const blumeConfigSchema: z.ZodObject<{
         structuredData: z.ZodDefault<z.ZodBoolean>;
     }, "strict", z.ZodTypeAny, {
         rss: {
-            enabled: boolean;
             limit: number;
+            enabled: boolean;
             types: string[];
         };
         metatags: Record<string, string>;
@@ -2633,8 +2719,8 @@ export declare const blumeConfigSchema: z.ZodObject<{
         structuredData: boolean;
     }, {
         rss?: {
-            enabled?: boolean | undefined;
             limit?: number | undefined;
+            enabled?: boolean | undefined;
             types?: string[] | undefined;
         } | undefined;
         metatags?: Record<string, string> | undefined;
@@ -2752,8 +2838,8 @@ export declare const blumeConfigSchema: z.ZodObject<{
     };
     seo: {
         rss: {
-            enabled: boolean;
             limit: number;
+            enabled: boolean;
             types: string[];
         };
         metatags: Record<string, string>;
@@ -2817,6 +2903,15 @@ export declare const blumeConfigSchema: z.ZodObject<{
                 slug?: string | undefined;
             } | undefined;
             publishedValue?: string | undefined;
+        } | {
+            type: "github-releases";
+            owner: string;
+            repo: string;
+            prefix?: string | undefined;
+            pollInterval?: number | undefined;
+            drafts?: boolean | undefined;
+            limit?: number | undefined;
+            prereleases?: boolean | undefined;
         } | {
             type: "mintlify";
             exclude: string[];
@@ -3121,8 +3216,8 @@ export declare const blumeConfigSchema: z.ZodObject<{
     } | undefined;
     seo?: {
         rss?: {
-            enabled?: boolean | undefined;
             limit?: number | undefined;
+            enabled?: boolean | undefined;
             types?: string[] | undefined;
         } | undefined;
         metatags?: Record<string, string> | undefined;
@@ -3186,6 +3281,15 @@ export declare const blumeConfigSchema: z.ZodObject<{
                 slug?: string | undefined;
             } | undefined;
             publishedValue?: string | undefined;
+        } | {
+            type: "github-releases";
+            owner: string;
+            repo: string;
+            prefix?: string | undefined;
+            pollInterval?: number | undefined;
+            drafts?: boolean | undefined;
+            limit?: number | undefined;
+            prereleases?: boolean | undefined;
         } | {
             type: "mintlify";
             exclude?: string[] | undefined;

package/docs/advanced/changelog.mdx

@@ -5,7 +5,8 @@ description: Author release notes as content, and Blume builds a timeline page a
 
 Blume ships a changelog out of the box. Write each release as a normal content
 file, mark it `type: changelog`, and Blume collects every entry into a generated
-timeline page and an RSS feed — no layout to build, no list to maintain.
+timeline page and an RSS feed — no layout to build, no list to maintain. Or skip
+the files entirely and [source your changelog from GitHub Releases](#from-github-releases).
 
 ## Write an entry
 
@@ -72,6 +73,32 @@ replace it with your own design, add a [custom page](/docs/advanced/custom-pages
 `pages/changelog.astro` — it takes over and Blume stops generating the default
 timeline.
 
+## 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:
+
+```ts blume.config.ts
+content: {
+  sources: [
+    { type: "filesystem", root: "content" },
+    {
+      type: "github-releases",
+      prefix: "changelog",
+      owner: "acme",
+      repo: "sdk",
+    },
+  ],
+}
+```
+
+The release name becomes the title, its tag becomes `changelog.version`, and its
+published date sorts the timeline. A private repo authenticates with the
+`GITHUB_TOKEN` environment variable. See
+[Content sources](/docs/content/sources#github-releases) for every option.
+
 ## The RSS feed
 
 Blume also builds a changelog feed at **`/changelog/rss.xml`**, sorted

package/docs/advanced/custom-pages.mdx

@@ -233,7 +233,6 @@ import data from "blume:data";
   headings={[]}
   themeMode={data.config.theme.mode}
   searchEnabled={data.config.search.enabled}
-  searchProvider={data.config.search.provider}
   indexable={true}
 >
   <h1>Pricing</h1>

package/docs/configuration/index.mdx

@@ -20,7 +20,8 @@ export default defineConfig({
 
 ## A complete example
 
-Every option Blume reads, with its default:
+A broader example touching the most common options (see each feature's guide for
+the rest):
 
 ```ts blume.config.ts lineNumbers
 import { defineConfig } from "blume";
@@ -238,7 +239,7 @@ the full reference.
 
 ```ts blume.config.ts lineNumbers
 seo: {
-  og: { enabled: false },
+  og: { enabled: true },
   rss: { enabled: true, types: ["blog", "changelog"] },
   sitemap: true,
   robots: true,
@@ -246,15 +247,15 @@ seo: {
 }
 ```
 
-| Option           | Default                 | Description                                   |
-| ---------------- | ----------------------- | --------------------------------------------- |
-| `og.enabled`     | `false`                 | Generate per-page Open Graph images.          |
-| `rss.enabled`    | `true`                  | Build feeds for blog and changelog content.   |
-| `rss.types`      | `["blog", "changelog"]` | Content types that each get a feed.           |
-| `rss.limit`      | `50`                    | Maximum items per feed.                       |
-| `sitemap`        | `true`                  | Generate sitemap.xml (needs deployment.site). |
-| `robots`         | `true`                  | Generate robots.txt with a Sitemap link.      |
-| `structuredData` | `true`                  | Emit schema.org JSON-LD in each page's head.  |
+| Option           | Default                 | Description                                             |
+| ---------------- | ----------------------- | ------------------------------------------------------- |
+| `og.enabled`     | auto                    | Per-page Open Graph images — on when a site URL is set. |
+| `rss.enabled`    | `true`                  | Build feeds for blog and changelog content.             |
+| `rss.types`      | `["blog", "changelog"]` | Content types that each get a feed.                     |
+| `rss.limit`      | `50`                    | Maximum items per feed.                                 |
+| `sitemap`        | `true`                  | Generate sitemap.xml (needs deployment.site).           |
+| `robots`         | `true`                  | Generate robots.txt with a Sitemap link.                |
+| `structuredData` | `true`                  | Emit schema.org JSON-LD in each page's head.            |
 
 These work best with an absolute [`deployment.site`](/docs/deployment) for full URLs.
 

package/docs/configuration/search.mdx

@@ -17,7 +17,8 @@ so picking one backend never pulls in the others.
 ## Using search
 
 Open search with <Badge variant="accent">⌘K</Badge> (or `Ctrl K`), or press `/`
-when you're not typing in a field. `Esc` closes it.
+when you're not typing in a field. `Esc` closes it, and `⌘J` (or `Ctrl J`)
+toggles the result preview pane.
 
 Queries match page **titles**, **descriptions**, and **body text**, with title
 matches ranked highest and descriptions above body.
@@ -29,6 +30,17 @@ to plain text — code blocks, images, and markup are stripped, so results stay
 relevant. The index is built from your source files, so it's identical in dev and
 production.
 
+## Tags
+
+Add `search.tags` to a page's frontmatter to group it under a filter in the
+search dialog — readers can narrow results to a tag with a click. Tags also
+become a facet on the hosted providers.
+
+```yaml
+search:
+  tags: [api, reference]
+```
+
 ## Providers
 
 The client-side providers are keyless and need no extra config. The hosted ones

package/docs/configuration/theming.mdx

@@ -98,6 +98,55 @@ Each value is a Google Fonts slug from the curated set below:
 Need a font that isn't listed, or want to drop back to the system stack? Override
 the `--blume-font-*` tokens directly in [`theme.css`](#theme-css).
 
+### Dark-mode colors
+
+By default light and dark share one `accent`. Set `accentDark` for a different
+accent in dark mode, and `background` / `backgroundDark` to override the page
+background per mode:
+
+```ts blume.config.ts lineNumbers
+theme: {
+  accent: "blue",
+  accentDark: "teal",        // a different accent in dark mode
+  background: "#ffffff",     // light-mode page background
+  backgroundDark: "#0a0a0a", // dark-mode page background
+}
+```
+
+Each takes a named preset or any CSS color, exactly like `accent`.
+
+### Action color
+
+`action` is a secondary accent for primary calls to action and the `action`
+Tailwind utilities (`bg-action`, `text-action`). It defaults to your `accent`:
+
+```ts blume.config.ts
+theme: {
+  action: "#ff0066",
+}
+```
+
+### Background decoration
+
+Add a subtle, theme-aware pattern behind your content with `backgroundDecoration`
+— `gradient`, `grid`, or `windows`:
+
+```ts blume.config.ts
+theme: {
+  backgroundDecoration: "grid",
+}
+```
+
+For a full background image, set `backgroundImage` (and `backgroundImageDark` for
+a dark variant) to a URL or a path under `public/`:
+
+```ts blume.config.ts lineNumbers
+theme: {
+  backgroundImage: "/bg-light.svg",
+  backgroundImageDark: "/bg-dark.svg",
+}
+```
+
 ## theme.css
 
 Drop a `theme.css` in your project root to override any design token. It's the
@@ -128,6 +177,7 @@ dark mode.
 | `--blume-border`            | Borders and dividers                      |
 | `--blume-accent`            | Accent color                              |
 | `--blume-accent-foreground` | Text and icons on an accent background    |
+| `--blume-action`            | Secondary accent (defaults to accent)     |
 | `--blume-code-background`   | Code block surface                        |
 | `--blume-radius`            | Corner radius                             |
 | `--blume-font-display`      | Heading font                              |
@@ -159,6 +209,7 @@ a utility, so your components track the theme automatically:
 | `--blume-border`            | `border-border`            |
 | `--blume-accent`            | `bg-accent`, `text-accent` |
 | `--blume-accent-foreground` | `text-accent-foreground`   |
+| `--blume-action`            | `bg-action`, `text-action` |
 | `--blume-radius`            | `rounded-blume`            |
 | `--blume-font-display`      | `font-display`             |
 | `--blume-font-body`         | `font-sans`                |

package/docs/content/components.mdx

@@ -133,6 +133,24 @@ A negative or breaking state, such as a deprecation.
 <Badge variant="danger">Deprecated</Badge>
 ```
 
+## Icon
+
+Render an icon from Blume's built-in set by name — the same set the `icon` props
+on cards, tiles, tabs, and sidebar entries draw from. Names are lowercase and
+kebab-cased (`rocket`, `book-open`, `chevron-right`).
+
+<Icon icon="rocket" size={20} />
+
+```astro
+<Icon icon="rocket" size={20} />
+```
+
+`icon` is the icon name; `size` sets the pixel size (default `16`) and `color`
+tints it (any CSS color; defaults to `currentColor`). Pass a raw `<svg>` string,
+an image URL, or a local image path in place of a name to render your own art,
+and add a `label` to expose it to assistive tech — without one, the icon is
+decorative.
+
 ## File tree
 
 Illustrate a project or folder layout. Wrap a normal Markdown list and Blume

package/docs/content/navigation.mdx

@@ -104,8 +104,14 @@ Tabs also **scope the sidebar**: when the current route falls under a tab's
 `path`, the sidebar shows only that section's pages — so `/adapters/*` lists the
 adapters and nothing else. The folder at a tab's `path` becomes the section, so
 this needs no extra config beyond the tabs themselves; structure your content
-into a folder per tab and point each tab at it. A route under no tab (or a tab
-whose `path` is `/`) shows the full sidebar.
+into a folder per tab and point each tab at it.
+
+On a route under no tab (or a tab whose `path` is `/`), the sidebar shows the
+pages that _don't_ belong to a tab — each tab's folder is hidden from it, since
+that section already has its own tab in the header. So a root landing page lists
+your loose top-level pages while the sectioned content stays behind its tab,
+mirroring Fumadocs' root folders. If a route has no pages of its own to show
+this way, the full tree is shown instead, so the sidebar is never left blank.
 
 ## Explicit sidebar
 

package/docs/content/sources.mdx

@@ -88,6 +88,49 @@ a remote source for changes instead, set `pollInterval` (seconds) on it — the
 dev server re-fetches on that interval and reloads only when the content
 actually changes. Leave it unset to avoid hitting the API while you work.
 
+## GitHub Releases
+
+The built-in `github-releases` source turns a repo's releases into a changelog:
+each release becomes a `type: changelog` entry, so your release notes _are_ your
+changelog — nothing to write twice. Combined with the generated
+[changelog timeline](/docs/advanced/changelog), publishing a GitHub release
+ships a changelog entry.
+
+```ts blume.config.ts
+import { defineConfig } from "blume";
+
+export default defineConfig({
+  content: {
+    sources: [
+      { type: "filesystem", root: "content" },
+      {
+        type: "github-releases",
+        prefix: "changelog",
+        owner: "acme",
+        repo: "sdk",
+        // prereleases: false,  // include prereleases (default off)
+        // drafts: false,       // include drafts (needs a write token)
+        // limit: 100,          // cap releases, newest-first
+      },
+    ],
+  },
+});
+```
+
+Each release maps to the changelog fields automatically: its name (or tag)
+becomes the title, its published date drives the timeline order, the tag becomes
+`changelog.version`, and prereleases are tagged `Prerelease` (others `Release`).
+The notes render as the entry body. Give the source a `prefix` so its release
+pages nest under a route like `/changelog/v1-2-0`.
+
+A private repo authenticates with the `GITHUB_TOKEN` environment variable — the
+same token the other GitHub features use, never inlined into your config. Like
+every remote source it's cached under `.blume/cache/<source>/` and served
+offline if the API is unreachable. Because a changelog is supplementary, a fetch
+failure with no cache (say a CI build without a token) degrades to an empty
+changelog with a warning rather than failing the build — set `GITHUB_TOKEN` in
+your CI and deploy environments to populate it.
+
 ## Sanity
 
 The built-in `sanity` source runs a GROQ query and maps each document's fields

package/docs/content/syntax.mdx

@@ -11,7 +11,7 @@ each.
 ## Headings
 
 Structure a page with headings. Blume renders your frontmatter `title` as the
-page heading, so start your content at `##` — `##` through `####` become entries
+page heading, so start your content at `##` — `##` and `###` become entries
 in the table of contents. Every `##`–`######` heading is also wrapped in a link
 to its own anchor, so readers can click a heading to copy, bookmark, or share a
 permalink straight to that section (hover to reveal the `#`). Turn this off with

package/docs/index.mdx

@@ -83,7 +83,7 @@ loosely-typed YAML.
 - **SEO** — metadata, Open Graph images, RSS feeds, and JSON-LD, [built in](/docs/configuration/seo).
 - **Customization** — component overrides, React islands, custom pages, theme
   tokens, and a source-component registry via `blume add`.
-- **Migration** — `blume migrate mintlify | starlight | fumadocs`.
+- **Migration** — `blume migrate mintlify | starlight | nextra | fumadocs`.
 - **Eject** — `blume eject` produces a standalone Astro project that still uses
   the `blume` package.
 

package/docs/reference/cli.mdx

@@ -17,14 +17,20 @@ blume <command> [options]
 | `blume preview`        | Preview the last build.                                |
 | `blume add <item>`     | Install a source component from the registry.          |
 | `blume migrate <tool>` | Migrate from Mintlify, Starlight, Nextra, or Fumadocs. |
+| `blume sync`           | Re-fetch remote content sources and regenerate.        |
 | `blume eject`          | Promote the runtime into a standalone Astro app.       |
 | `blume doctor`         | Diagnose config and content problems.                  |
 | `blume validate`       | Validate links across your content.                    |
 
 ## Common flags
 
+- `blume init --content-dir <dir> --yes` — set the content folder (default `docs`) and skip prompts.
 - `blume dev --host --port <n> --open`
-- `blume build --strict` — fail on diagnostics.
+- `blume dev --preview` / `blume build --preview` — include drafts and unpublished CMS content.
+- `blume build --strict` — fail the build on diagnostic errors (also works on `blume dev`).
+- `blume preview --host --port <n>` — bind the preview server.
+- `blume sync --force` — re-fetch remote sources, dropping the cached snapshot first.
+- `blume add <item> --force` — overwrite files that already exist.
 - `blume eject --yes` — skip the confirmation prompt.
 - `blume validate --external` — also check external links over the network.
 - `blume validate --strict` — exit non-zero on warnings too.

package/docs/reference/frontmatter.mdx

@@ -24,6 +24,11 @@ Every page accepts the following frontmatter. All fields are optional.
       default: "false",
       description: "Exclude from production builds.",
     },
+    lastModified: {
+      type: "string",
+      description:
+        'Pin the page\'s "last updated" date (ISO or YAML date); overrides the git-derived date.',
+    },
   }}
 />
 
@@ -33,7 +38,8 @@ Every page accepts the following frontmatter. All fields are optional.
 sidebar:
   label: Install
   order: 2
-  icon: Download
+  icon: download
+  badge: New
   hidden: false
 ```
 
@@ -42,7 +48,9 @@ sidebar:
 ```yaml lineNumbers
 seo:
   title: Install Blume
+  description: Install Blume and scaffold your first project.
   image: /og/install.png
+  canonical: https://acme.com/install
   noindex: false
 ```
 

package/package.json

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

package/src/astro/generate.ts

@@ -813,6 +813,28 @@ export interface GenerateResult {
   warnings: string[];
 }
 
+/**
+ * Whether to generate the default `/changelog` index. Written when there are
+ * `type: changelog` entries — or when a release-backed changelog source is
+ * configured, so its route (and any nav tab pointing at it) still resolves to an
+ * empty timeline on a build where the source could not be fetched (e.g. CI
+ * without a token). Skipped when a user content page already owns `/changelog`.
+ */
+const shouldGenerateChangelog = (project: BlumeProject): boolean => {
+  const hasChangelog = project.graph.pages.some(
+    (page) =>
+      page.contentType === "changelog" &&
+      !(page.meta.draft || page.meta.sidebar.hidden)
+  );
+  const hasChangelogSource = (project.config.content.sources ?? []).some(
+    (source) => source.type === "github-releases"
+  );
+  const changelogRouteTaken = project.graph.pages.some(
+    (page) => page.route === "/changelog"
+  );
+  return (hasChangelog || hasChangelogSource) && !changelogRouteTaken;
+};
+
 /**
  * Write (or update) the generated `.blume/` Astro runtime for a project.
  * Only files whose content changed are rewritten so Vite HMR stays fast.
@@ -987,21 +1009,16 @@ export const generateRuntime = async (
     );
   }
 
-  // Changelog index (`/changelog`): a timeline of every `type: changelog` entry,
-  // rendered through the Update layout. Skipped when there are no entries, or
-  // when a user content page already occupies the `/changelog` route.
-  const hasChangelog = project.graph.pages.some(
-    (page) =>
-      page.contentType === "changelog" &&
-      !(page.meta.draft || page.meta.sidebar.hidden)
-  );
-  const changelogRouteTaken = project.graph.pages.some(
-    (page) => page.route === "/changelog"
-  );
-  if (hasChangelog && !changelogRouteTaken) {
+  // Changelog index (`/changelog`), rendered through the Update timeline layout.
+  if (shouldGenerateChangelog(project)) {
     await write(
       join(srcDir, "pages", "changelog.astro"),
-      changelogIndexTemplate({ askEnabled, exportEpub, exportPdf })
+      changelogIndexTemplate({
+        askEnabled,
+        exportEpub,
+        exportPdf,
+        staged: hasStaged,
+      })
     );
   }
 

package/src/astro/templates.ts

@@ -1056,11 +1056,18 @@ export const changelogIndexTemplate = (options: {
   askEnabled: boolean;
   exportEpub: boolean;
   exportPdf: boolean;
+  /** Whether a `staged` collection exists (non-filesystem changelog sources). */
+  staged: boolean;
 }): string => {
   const askImport = options.askEnabled
     ? 'import AskAI from "blume/components/islands/AskAI.astro";\n'
     : "";
   const askSlot = options.askEnabled ? '\n  <AskAI slot="ask" />' : "";
+  // Staged sources (e.g. GitHub Releases) render through a parallel collection,
+  // so fold them in alongside filesystem entries when one exists.
+  const stagedSpread = options.staged
+    ? '\n  ...(await getCollection("staged")),'
+    : "";
 
   return `---
 // Generated by Blume. Do not edit.
@@ -1100,7 +1107,9 @@ const slugify = (text) =>
   text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") ||
   "update";
 
-const changelogEntries = (await getCollection("docs"))
+const changelogEntries = [
+  ...(await getCollection("docs")),${stagedSpread}
+]
   .filter(
     (entry) =>
       entry.data.type === "changelog" &&