From 3971c07b1abb9e39fc5987bf16658b44d304e13a Mon Sep 17 00:00:00 2001
From: AriaEdo <aria.edo@gmail.com>
Date: Thu, 12 Nov 2026 18:05:18 +0700
Subject: [PATCH] feat(changelog): source /changelog from the Mintlify docs
 changelog

The docs changelog (datum-cloud/docs changelog.mdx, served at
/docs/changelog) is the source of truth. /changelog now reads the same
file instead of GitHub Discussions, so both pages always show the same
entries.

- Parse <Update> blocks into entries: the ## heading is the title, the
  description is the product, tags become labels, and docs-relative
  links are rewritten to /docs/...
- Throw on any block that cannot be parsed so a format change in the
  docs repo surfaces as an error instead of silently dropped entries.
- Cache the parsed entries for 20 minutes; failures are logged and not
  cached.
- /changelog.md renders from the same source.
- Show the product as an eyebrow above the title and move tags under
  the date, styled like the roadmap backlog badge.
- Remove the stale 2025 markdown entries (index.md keeps page meta).
- Add parser unit tests (npm run test:changelog).
---
 package.json                               |   3 +-
 src/components/changelog/Card.astro        |  36 +++----
 src/content/changelog/0.0.1.md             |  20 ----
 src/content/changelog/0.1.0.md             |  21 ----
 src/content/changelog/0.1.1.md             |  27 ------
 src/libs/changelogMdx.ts                   |  94 ++++++++++++++++++
 src/libs/datum.ts                          | 108 ++++-----------------
 src/pages/changelog.md.ts                  |  43 +++-----
 src/static/styles/components-changelog.css |  22 ++---
 tests/changelogMdx.test.ts                 |  93 ++++++++++++++++++
 tests/e2e/changelog-search.spec.ts         |   4 +-
 11 files changed, 249 insertions(+), 222 deletions(-)
 delete mode 100644 src/content/changelog/0.0.1.md
 delete mode 100644 src/content/changelog/0.1.0.md
 delete mode 100644 src/content/changelog/0.1.1.md
 create mode 100644 src/libs/changelogMdx.ts
 create mode 100644 tests/changelogMdx.test.ts

diff --git a/package.json b/package.json
index 0074bd091..a5af754ae 100644
--- a/package.json
+++ b/package.json
@@ -26,7 +26,8 @@
     "test:e2e:ui": "playwright test --ui",
     "test:e2e:debug": "playwright test --debug",
     "test:e2e:report": "playwright show-report",
-    "test:server": "node --test tests/server.test.mjs"
+    "test:server": "node --test tests/server.test.mjs",
+    "test:changelog": "node --test tests/changelogMdx.test.ts"
   },
   "dependencies": {
     "@alpinejs/collapse": "^3.17.1",
diff --git a/src/components/changelog/Card.astro b/src/components/changelog/Card.astro
index 522103cc7..a637d326f 100644
--- a/src/components/changelog/Card.astro
+++ b/src/components/changelog/Card.astro
@@ -69,6 +69,7 @@ function embedGithubVideos(html: string): string {
             <ChangelogDot aria-hidden="true" />
           </div>
           <div class="changelog-entry-nav-content">
+            {entry.product && <span class="changelog-entry-nav-product">{entry.product}</span>}
             <h3 class="changelog-entry-nav-title">{entry.title}</h3>
             <div class="changelog-entry-nav-date-row">
               <time class="changelog-entry-nav-date">
@@ -78,6 +79,24 @@ function embedGithubVideos(html: string): string {
                   year: 'numeric',
                 })}
               </time>
+              {entry.labels && entry.labels.nodes.length > 0 && (
+                <div class="changelog-entry-card-tags">
+                  {entry.labels.nodes.map((label) => (
+                    <div class="changelog-entry-card-tag-row">
+                      <span
+                        class={`changelog-entry-card-tag changelog-entry-card-tag--${label.name.toLowerCase().replace(/[^a-z0-9]+/g, '-')}`}
+                      >
+                        {label.name}
+                      </span>
+                      {label.description && (
+                        <span class="changelog-entry-card-tag-description">
+                          {label.description}
+                        </span>
+                      )}
+                    </div>
+                  ))}
+                </div>
+              )}
             </div>
           </div>
         </div>
@@ -98,23 +117,6 @@ function embedGithubVideos(html: string): string {
             class="changelog-entry-card-body"
             set:html={embedGithubVideos(marked.parse(entry.body) as string)}
           />
-
-          {entry.labels && entry.labels.nodes.length > 0 && (
-            <div class="changelog-entry-card-tags">
-              {entry.labels.nodes.map((label) => (
-                <div class="changelog-entry-card-tag-row">
-                  <span
-                    class={`changelog-entry-card-tag changelog-entry-card-tag--${label.name.toLowerCase()}`}
-                  >
-                    {label.name}
-                  </span>
-                  {label.description && (
-                    <span class="changelog-entry-card-tag-description">{label.description}</span>
-                  )}
-                </div>
-              ))}
-            </div>
-          )}
         </article>
       </div>
     ))
diff --git a/src/content/changelog/0.0.1.md b/src/content/changelog/0.0.1.md
deleted file mode 100644
index 926ef3a57..000000000
--- a/src/content/changelog/0.0.1.md
+++ /dev/null
@@ -1,20 +0,0 @@
----
-title: "Real-time visibility and monitoring now available"
-date: 2025-09-10
-description: "v0.0.1"
-tags:
-  - label: New
-    type: new
-    value: New features added
----
-
-We’ve introduced a self-service telemetry dashboard for real-time visibility into HTTP Proxy instances. Monitor performance, understand traffic patterns, and troubleshoot services across deployed edge locations.
-
-Highlights:
-- Self-Service Monitoring – View proxy metrics without needing support intervention.
-- Real-Time Visibility – Live metrics with automatic refresh for immediate service health awareness.
-- Traffic Insights – Understand traffic patterns, geographic distribution, and performance details.
-- Troubleshooting Support – Diagnose and resolve proxy-related issues with actionable data.
-- Performance Transparency – Track key metrics including request rates, response times, error rates, and connection health.
-
-View the work history on [enhancement #228](https://github.com/datum-cloud/enhancements/issues/228)
\ No newline at end of file
diff --git a/src/content/changelog/0.1.0.md b/src/content/changelog/0.1.0.md
deleted file mode 100644
index 49d9f491c..000000000
--- a/src/content/changelog/0.1.0.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Activity logs improvements"
-date: 2025-09-30
-description: "v0.1.0"
-tags:
-  - label: Fixed
-    type: fixed
-    value: Bug fixes and improvements
-  - label: New
-    type: new
-    value: New features added
----
-
-We’ve made it easier to browse and filter activity logs.
-
-Highlights:
-- Relative Time Filters – Use options like Last X minutes, similar to Grafana.
-- Action Filters – Use a predefined dropdown of available actions to focus on key events.
-- Streamlined Browsing – Improved navigation for reviewing recent activity.
-
-Check out the history on [enhancement #130](https://github.com/datum-cloud/staff-portal/issues/130)
diff --git a/src/content/changelog/0.1.1.md b/src/content/changelog/0.1.1.md
deleted file mode 100644
index 84bf473af..000000000
--- a/src/content/changelog/0.1.1.md
+++ /dev/null
@@ -1,27 +0,0 @@
----
-title: "Account Profile Options"
-date: 2025-09-10
-description: "v0.1.1"
-tags:
-  # - label: Fixed
-  #   type: fixed
-  #   value: Bug fixes and improvements
-  - label: New
-    type: new
-    value: New features added
-  # - label: Changed
-  #   type: changed
-  #   value: Existing features modified
----
-
-We’ve enhanced the Account Settings page to offer more control.
-
-Highlights:
-- Profile Updates – Change first and last name.
-- Account Identities – View linked accounts (e.g., Google Workspace, GitHub).
-- Timezone Control – Set preferred timezone.
-- Portal Preferences – Adjust settings like theme.
-- Email Subscriptions – Opt in or out of newsletters.
-- Account Deletion – Permanently delete an account when needed.
-
-Looking for the details? See [issue #50](https://github.com/datum-cloud/enhancements/issues/50) and [issue #141](https://github.com/datum-cloud/enhancements/issues/141)
\ No newline at end of file
diff --git a/src/libs/changelogMdx.ts b/src/libs/changelogMdx.ts
new file mode 100644
index 000000000..b52bb3e63
--- /dev/null
+++ b/src/libs/changelogMdx.ts
@@ -0,0 +1,94 @@
+// Parses the Mintlify changelog (datum-cloud/docs `changelog.mdx`), the single
+// source of truth for both /docs/changelog and the marketing /changelog page.
+// The parser throws on any block it cannot read: a format change in the docs
+// repo must surface as an error, never as silently missing entries.
+import type { ChangelogProps } from './datum';
+
+export const DOCS_CHANGELOG_SOURCE_URL =
+  'https://raw.githubusercontent.com/datum-cloud/docs/main/changelog.mdx';
+export const CHANGELOG_DISCUSSIONS_URL =
+  'https://github.com/orgs/datum-cloud/discussions/categories/changelog';
+
+const DOCS_BASE_PATH = '/docs';
+const UPDATE_OPEN_TAG = /<Update\b/g;
+const UPDATE_BLOCK = /<Update\s+([^>]*?)>\r?\n([\s\S]*?)\r?\n\s*<\/Update>/g;
+const DISCUSSION_LINK = /https:\/\/github\.com\/orgs\/datum-cloud\/discussions\/\d+/;
+
+function readStringAttr(attrs: string, name: string): string | undefined {
+  return attrs.match(new RegExp(`${name}="([^"]*)"`))?.[1];
+}
+
+function readTags(attrs: string): string[] {
+  const raw = attrs.match(/tags=\{(\[[^\]]*\])\}/)?.[1];
+  if (!raw) return [];
+  const parsed: unknown = JSON.parse(raw);
+  if (!Array.isArray(parsed) || !parsed.every((t) => typeof t === 'string')) {
+    throw new Error(`Invalid changelog tags ${raw}`);
+  }
+  return parsed;
+}
+
+function dedent(text: string): string {
+  const lines = text.split('\n');
+  const indents = lines
+    .filter((line) => line.trim())
+    .map((line) => line.match(/^ */)?.[0].length ?? 0);
+  const minIndent = indents.length ? Math.min(...indents) : 0;
+  return lines
+    .map((line) => line.slice(minIndent))
+    .join('\n')
+    .trim();
+}
+
+function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+function parseLabelDate(label: string): Date {
+  // Noon UTC keeps the same calendar day in every server timezone.
+  const date = new Date(`${label} 12:00:00 UTC`);
+  if (isNaN(date.getTime())) throw new Error(`Invalid changelog date "${label}"`);
+  return date;
+}
+
+function parseBlock(attrs: string, content: string): ChangelogProps {
+  const label = readStringAttr(attrs, 'label');
+  if (!label) throw new Error(`Changelog <Update ${attrs}> is missing a label`);
+  const createdAt = parseLabelDate(label);
+
+  const body = dedent(content);
+  const heading = body.match(/^## +(.+)$/m);
+  if (!heading) throw new Error(`Changelog entry "${label}" is missing a "## " heading`);
+  const title = heading[1].trim();
+
+  const bodyWithoutTitle = body
+    .replace(heading[0], '')
+    .trim()
+    .replace(/\]\(\/(?!\/)/g, `](${DOCS_BASE_PATH}/`);
+
+  return {
+    id: `${createdAt.toISOString().slice(0, 10)}-${slugify(title)}`,
+    title,
+    body: bodyWithoutTitle,
+    url: body.match(DISCUSSION_LINK)?.[0] ?? CHANGELOG_DISCUSSIONS_URL,
+    createdAt,
+    product: readStringAttr(attrs, 'description'),
+    labels: { nodes: readTags(attrs).map((name) => ({ name, color: '' })) },
+  };
+}
+
+export function parseDocsChangelog(mdx: string): ChangelogProps[] {
+  const expected = mdx.match(UPDATE_OPEN_TAG)?.length ?? 0;
+  if (expected === 0) throw new Error('No <Update> entries found in docs changelog');
+
+  const entries = [...mdx.matchAll(UPDATE_BLOCK)].map(([, attrs, content]) =>
+    parseBlock(attrs, content)
+  );
+  if (entries.length !== expected) {
+    throw new Error(`Parsed ${entries.length} of ${expected} <Update> blocks in docs changelog`);
+  }
+  return entries;
+}
diff --git a/src/libs/datum.ts b/src/libs/datum.ts
index 805dbd87a..f27fa34a5 100644
--- a/src/libs/datum.ts
+++ b/src/libs/datum.ts
@@ -1,5 +1,6 @@
 import { graph } from '@libs/github';
 import { Cache } from '@libs/cache';
+import { DOCS_CHANGELOG_SOURCE_URL, parseDocsChangelog } from '@libs/changelogMdx';
 
 const cache = new Cache('.cache');
 const owner = 'datum-cloud';
@@ -20,6 +21,7 @@ type ChangelogProps = {
   body: string;
   url: string;
   createdAt: Date;
+  product?: string;
   labels?: { nodes: Array<{ name: string; color: string; description?: string }> };
 };
 
@@ -146,104 +148,28 @@ async function roadmaps(): Promise<RoadmapProps[]> {
   return roadmaps;
 }
 
+// Source of truth is the Mintlify changelog (/docs/changelog), so the
+// marketing page always matches the docs. Errors are logged and not cached,
+// so the next request retries.
 async function changelogs(): Promise<ChangelogProps[]> {
-  type ResponseProps = {
-    repository: {
-      discussions: {
-        nodes: [
-          {
-            id: string;
-            title: string;
-            body: string;
-            url: string;
-            labels: {
-              nodes: Array<{
-                name: string;
-                color: string;
-                description?: string;
-              }>;
-            };
-          },
-        ];
-      };
-    };
-  };
-
-  const name = 'datum';
-  let changelogs: ChangelogProps[] = [];
-  const categoryVariables = {
-    owner,
-    name,
-    slug: 'changelog',
-  };
-
   if (await cache.has('changelogs')) {
     return (await cache.get<ChangelogProps[]>('changelogs')) ?? [];
   }
-  {
-    try {
-      const categoryQuery = `
-        query ($owner:String!, $name:String!, $slug:String!) {
-          repository(owner: $owner, name: $name) {
-            discussionCategory(slug: $slug){
-              id,
-            }
-          }
-        }`;
-
-      const categoryResponse = (await graph(categoryQuery, categoryVariables)) as {
-        repository: { discussionCategory: { id: string } };
-      };
-
-      if (
-        !categoryResponse ||
-        !categoryResponse.repository ||
-        !categoryResponse.repository.discussionCategory
-      ) {
-        return changelogs;
-      }
-
-      const categoryId = categoryResponse.repository.discussionCategory.id as string;
-      const query = `
-        query ($owner:String!, $name:String!, $categoryId:ID!) {
-          repository(owner: $owner, name: $name) {
-            discussions(first: 30, after: null, categoryId: $categoryId) {
-              nodes {
-                id,
-                title,
-                body,
-                url,
-                createdAt,
-                labels (first: 5, last: null) {
-                  nodes {
-                    name,
-                    color,
-                    description,
-                  }
-                },
-              }
-            }
-          }
-        }
-      `;
 
-      const variables = {
-        owner,
-        name,
-        categoryId,
-      };
-
-      const response = (await graph(query, variables)) as ResponseProps;
-      changelogs = Object(response.repository.discussions.nodes).map((log: ChangelogProps) => ({
-        ...log,
-      }));
-      await cache.set('changelogs', changelogs, 1000 * 60 * 10); // cache for 10 minutes
-    } catch {
-      changelogs = [];
+  try {
+    const response = await fetch(DOCS_CHANGELOG_SOURCE_URL, {
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status} fetching ${DOCS_CHANGELOG_SOURCE_URL}`);
     }
+    const entries = parseDocsChangelog(await response.text());
+    await cache.set('changelogs', entries, 1000 * 60 * 20); // cache for 20 minutes
+    return entries;
+  } catch (error) {
+    console.error('Failed to load changelog from docs:', error);
+    return [];
   }
-
-  return changelogs;
 }
 
 export { stargazerCount, roadmaps, changelogs, type RoadmapProps, type ChangelogProps };
diff --git a/src/pages/changelog.md.ts b/src/pages/changelog.md.ts
index 45dd57c6a..2885bb934 100644
--- a/src/pages/changelog.md.ts
+++ b/src/pages/changelog.md.ts
@@ -1,40 +1,25 @@
-import type { APIRoute } from 'astro';
-import { getCollection, getEntry } from 'astro:content';
-import { markdownSeoHeaders, renderEntryMarkdown, stripMdxToMarkdown } from '@utils/pageMarkdown';
-
-interface ChangelogEntry {
-  data: { title?: string; description?: string; date?: string | Date };
-  body?: string;
-  id: string;
-}
+// Dynamic markdown export of /changelog. Pulls from the same Mintlify
+// changelog (/docs/changelog) that Card.astro renders from. SSR so new docs
+// entries show up without a site rebuild.
+export const prerender = false;
 
-function formatDate(d?: string | Date): string {
-  if (!d) return '';
-  const dt = typeof d === 'string' ? new Date(d) : d;
-  if (isNaN(dt.getTime())) return typeof d === 'string' ? d : '';
-  return dt.toISOString().slice(0, 10);
-}
+import type { APIRoute } from 'astro';
+import { getEntry } from 'astro:content';
+import { changelogs } from '@libs/datum';
+import { markdownSeoHeaders, renderEntryMarkdown } from '@utils/pageMarkdown';
 
 export const GET: APIRoute = async () => {
   try {
     const index = await getEntry('changelog', 'index');
-    const allEntries = (await getCollection('changelog')) as unknown as ChangelogEntry[];
-    const entries = allEntries
-      .filter((e) => e.id !== 'index')
-      .sort((a, b) => {
-        const da = a.data.date ? new Date(a.data.date).getTime() : 0;
-        const db = b.data.date ? new Date(b.data.date).getTime() : 0;
-        return db - da;
-      });
+    const entries = await changelogs();
 
     const sections: string[] = [];
     for (const entry of entries) {
-      const date = formatDate(entry.data.date);
-      const heading = date ? `## ${entry.data.title} - ${date}` : `## ${entry.data.title}`;
-      sections.push(heading);
-      if (entry.data.description) sections.push('', `_${entry.data.description}_`);
-      const body = stripMdxToMarkdown(entry.body ?? '');
-      if (body) sections.push('', body);
+      const date = new Date(entry.createdAt).toISOString().slice(0, 10);
+      sections.push(`## ${entry.title} - ${date}`);
+      const tags = entry.labels?.nodes.map((l) => l.name) ?? [];
+      if (tags.length) sections.push('', `_${tags.join(', ')}_`);
+      if (entry.body) sections.push('', entry.body);
       sections.push('');
     }
 
diff --git a/src/static/styles/components-changelog.css b/src/static/styles/components-changelog.css
index 488fefffd..e15ca4608 100644
--- a/src/static/styles/components-changelog.css
+++ b/src/static/styles/components-changelog.css
@@ -144,6 +144,11 @@
     @apply flex min-w-0 flex-col gap-4;
   }
 
+  /* Product eyebrow above the title; -mb-2 tightens the nav-content gap to pair it with the title */
+  .changelog-entry-nav-product {
+    @apply datum-text-smallcaps text-canyon-clay -mb-2 uppercase;
+  }
+
   .changelog-entry-nav-title {
     @apply text-midnight-fjord m-0 font-semibold xl:text-(length:--30px) xl:leading-(--42px);
   }
@@ -226,27 +231,16 @@
   }
 
   .changelog-entry-card-tags {
-    @apply flex flex-col gap-4;
+    @apply flex flex-wrap gap-2;
   }
 
   .changelog-entry-card-tag-row {
     @apply flex items-center gap-6;
   }
 
+  /* Matches .roadmap-backlog-badge (components-roadmap.css) */
   .changelog-entry-card-tag {
-    @apply datum-text-sm text-midnight-fjord w-23 shrink-0 rounded-sm border-l-3 px-3.5 py-2 text-center font-semibold;
-  }
-
-  .changelog-entry-card-tag--changed {
-    @apply border-canyon-clay bg-blush-quartz;
-  }
-
-  .changelog-entry-card-tag--new {
-    @apply border-potted-olive bg-potted-olive/60;
-  }
-
-  .changelog-entry-card-tag--fixed {
-    @apply border-pine-forge/20 bg-aurora-moss;
+    @apply text-app---dark---utility-4 datum-app-body shrink-0 rounded-lg border border-current/30 px-1.5 py-0.5;
   }
 
   .changelog-entry-card-tag-description {
diff --git a/tests/changelogMdx.test.ts b/tests/changelogMdx.test.ts
new file mode 100644
index 000000000..a02c9e4ca
--- /dev/null
+++ b/tests/changelogMdx.test.ts
@@ -0,0 +1,93 @@
+// The Mintlify changelog (datum-cloud/docs changelog.mdx) is the single source
+// of truth for /changelog. These tests pin the contract between that file's
+// format and the marketing page, so a format change in the docs repo fails
+// loudly here instead of silently dropping or mangling entries on the site.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { parseDocsChangelog, CHANGELOG_DISCUSSIONS_URL } from '../src/libs/changelogMdx.ts';
+
+const FIXTURE = `---
+title: "Changelog"
+rss: true
+---
+
+Intro text with a [roadmap](/platform/roadmap) link that is not an entry.
+
+<Update label="November 10, 2026" description="Application Load Balancer" tags={["Fix"]}>
+  ## New load balancers serve traffic sooner
+
+  - **Fixed:** a new ALB no longer returns \`503\`.
+
+  See [ALB troubleshooting](/alb/troubleshooting) or the [portal](https://cloud.datum.net).
+</Update>
+
+<Update label="October 13, 2026" description="datumctl" tags={["AX/DX/UX", "Early access"]}>
+  ## New datumctl plugins
+
+  Install plugins.
+
+  [Read the announcement](https://github.com/orgs/datum-cloud/discussions/306)
+</Update>
+`;
+
+test('parses every <Update> block in source order (newest first, as authored in docs)', () => {
+  const entries = parseDocsChangelog(FIXTURE);
+  assert.equal(entries.length, 2);
+  assert.deepEqual(
+    entries.map((e) => e.title),
+    ['New load balancers serve traffic sooner', 'New datumctl plugins']
+  );
+});
+
+test('uses the ## heading as title and removes it from the body so the card does not repeat it', () => {
+  const [entry] = parseDocsChangelog(FIXTURE);
+  assert.ok(!entry.body.includes('## New load balancers'));
+  assert.ok(entry.body.startsWith('- **Fixed:**'), 'body must be dedented, not indented code');
+});
+
+test('rewrites docs-relative links to /docs so they resolve from www.datum.net/changelog', () => {
+  const [entry] = parseDocsChangelog(FIXTURE);
+  assert.ok(entry.body.includes('](/docs/alb/troubleshooting)'));
+  assert.ok(entry.body.includes('](https://cloud.datum.net)'), 'absolute links are untouched');
+});
+
+test('links to the entry discussion when present, otherwise to the changelog discussions category', () => {
+  const [withoutAnnouncement, withAnnouncement] = parseDocsChangelog(FIXTURE);
+  assert.equal(withAnnouncement.url, 'https://github.com/orgs/datum-cloud/discussions/306');
+  assert.equal(withoutAnnouncement.url, CHANGELOG_DISCUSSIONS_URL);
+});
+
+test('maps docs tags to labels and the label date to a timezone-safe createdAt', () => {
+  const [, entry] = parseDocsChangelog(FIXTURE);
+  assert.deepEqual(
+    entry.labels.nodes.map((l) => l.name),
+    ['AX/DX/UX', 'Early access']
+  );
+  // Noon UTC renders as the same calendar day in every server timezone (UTC-11..UTC+11).
+  assert.equal(new Date(entry.createdAt).toISOString(), '2026-10-13T12:00:00.000Z');
+  assert.equal(entry.id, '2026-10-13-new-datumctl-plugins');
+});
+
+test('keeps the <Update> description as the product name shown on the card', () => {
+  const [alb, cli] = parseDocsChangelog(FIXTURE);
+  assert.equal(alb.product, 'Application Load Balancer');
+  assert.equal(cli.product, 'datumctl');
+
+  const withoutDescription = FIXTURE.replace(' description="datumctl"', '');
+  assert.equal(parseDocsChangelog(withoutDescription)[1].product, undefined);
+});
+
+test('fails loudly when an <Update> block cannot be parsed instead of dropping it', () => {
+  const broken = FIXTURE.replace('label="October 13, 2026"', 'label="sometime soon"');
+  assert.throws(() => parseDocsChangelog(broken), /Invalid changelog date "sometime soon"/);
+
+  const noHeading = FIXTURE.replace('## New datumctl plugins', 'New datumctl plugins');
+  assert.throws(() => parseDocsChangelog(noHeading), /missing a "## " heading/);
+
+  const unclosed = FIXTURE.replace(/<\/Update>\s*$/, '');
+  assert.throws(() => parseDocsChangelog(unclosed), /Parsed 1 of 2 <Update> blocks/);
+});
+
+test('fails loudly when the source has no entries (e.g. an error page was fetched)', () => {
+  assert.throws(() => parseDocsChangelog('<html>404</html>'), /No <Update> entries/);
+});
diff --git a/tests/e2e/changelog-search.spec.ts b/tests/e2e/changelog-search.spec.ts
index 75084ca48..fd503f215 100644
--- a/tests/e2e/changelog-search.spec.ts
+++ b/tests/e2e/changelog-search.spec.ts
@@ -1,7 +1,7 @@
 import { test, expect } from '@playwright/test';
 
-// The changelog comes from GitHub Discussions; without credentials the page has no entries,
-// so these tests skip instead of failing.
+// The changelog comes from the docs repo (changelog.mdx); if it cannot be fetched the page has
+// no entries, so these tests skip instead of failing.
 test.describe('Changelog search', () => {
   test.beforeEach(async ({ page }) => {
     await page.goto('/changelog');