specra 0.2.66 → 0.2.68

package/dist/components/docs/SidebarMenuItems.svelte

@@ -4,6 +4,8 @@
   import { ChevronRight, ChevronDown, Lock } from 'lucide-svelte';
   import type { SpecraConfig } from '../../config.types.js';
   import Icon from './Icon.svelte';
+  import SidebarBadge from './SidebarBadge.svelte';
+  import { resolveBadges, type BadgeInput } from '../../badges.js';
   import { sortSidebarItems, sortSidebarGroups } from '../../sidebar-utils.js';
   import { renderInlineCode } from '../../inline.js';
 
@@ -21,11 +23,13 @@
     categoryCollapsed?: boolean;
     categoryIcon?: string;
     categoryTabGroup?: string;
+    categoryBadge?: BadgeInput;
     meta?: {
       icon?: string;
       tab_group?: string;
       sidebar_position?: number;
       order?: number;
+      badge?: BadgeInput;
       [key: string]: any;
     };
   }
@@ -34,6 +38,7 @@
     label: string;
     path: string;
     icon?: string;
+    badge?: BadgeInput;
     items: DocItem[];
     position: number;
     collapsible: boolean;
@@ -150,6 +155,7 @@
         if (isIndexFile) {
           rootGroups[groupName].position = doc.sidebar_position ?? 999;
           rootGroups[groupName].icon = doc.categoryIcon;
+          rootGroups[groupName].badge = doc.categoryBadge;
         }
         rootGroups[groupName].items.push(doc);
         return;
@@ -168,14 +174,19 @@
             .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
             .join(' ');
 
+          const isOwnCategory = i === folderParts.length - 1;
+
           if (!currentLevel[folder]) {
             currentLevel[folder] = {
               label:
-                doc.categoryLabel && i === folderParts.length - 1
+                doc.categoryLabel && isOwnCategory
                   ? doc.categoryLabel
                   : folderLabel,
               path: currentPath,
               icon: doc.categoryIcon,
+              // A doc's `_category_.json` describes its *own* folder, so the
+              // badge must not leak onto the ancestor folders we walk through.
+              badge: isOwnCategory ? doc.categoryBadge : undefined,
               items: [],
               position: doc.categoryPosition ?? 999,
               collapsible: doc.categoryCollapsible ?? true,
@@ -184,7 +195,10 @@
             };
           }
 
-          if (i === folderParts.length - 1) {
+          if (isOwnCategory) {
+            if (doc.categoryBadge) {
+              currentLevel[folder].badge = doc.categoryBadge;
+            }
             if (isIndexFile) {
               currentLevel[folder].position =
                 doc.categoryPosition ?? doc.sidebar_position ?? 999;
@@ -287,6 +301,7 @@
   {@const marginLeft = depth > 0 ? 'ml-4' : ''}
   {@const groupHref = getGroupHref(group)}
   {@const mergedItems = getMergedItems(group)}
+  {@const groupBadges = resolveBadges(group.badge)}
 
   <div class="space-y-1 {marginLeft}">
     <div class="flex items-center group">
@@ -296,14 +311,21 @@
           e.preventDefault();
           toggleSection(groupKey);
         }}
-        class="flex items-center gap-2 flex-1 px-3 py-2 text-sm font-semibold rounded-l-xl transition-all {isGroupActive
+        class="flex items-center gap-2 flex-1 min-w-0 px-3 py-2 text-sm font-semibold rounded-l-xl transition-all {isGroupActive
           ? 'bg-primary/10 text-primary'
           : 'text-foreground hover:bg-accent/50'}"
       >
         {#if group.icon}
           <Icon icon={group.icon} size={16} className="shrink-0" />
         {/if}
-        {@html renderInlineCode(group.label)}
+        <span class="truncate">{@html renderInlineCode(group.label)}</span>
+        {#if groupBadges.length > 0}
+          <span class="ml-auto flex items-center gap-1 shrink-0">
+            {#each groupBadges as badge (badge.text)}
+              <SidebarBadge {badge} />
+            {/each}
+          </span>
+        {/if}
       </a>
 
       {#if hasContent && group.collapsible && config.navigation?.collapsibleSidebar}
@@ -333,19 +355,27 @@
           {:else}
             {@const href = `${docsBase}/${item.doc.slug}`}
             {@const isActive = pathname === href}
+            {@const badges = resolveBadges(item.doc.meta?.badge)}
             <a
               {href}
               onclick={onLinkClick}
-              class="flex items-center gap-2 px-3 py-2 text-sm rounded-xl transition-all {isActive
+              class="flex items-center gap-2 min-w-0 px-3 py-2 text-sm rounded-xl transition-all {isActive
                 ? 'bg-primary/10 text-primary font-medium'
                 : 'text-foreground hover:text-foreground hover:bg-accent/50'}"
             >
               {#if item.doc.meta?.icon}
                 <Icon icon={item.doc.meta.icon} size={16} className="shrink-0" />
               {/if}
-              {@html renderInlineCode(item.doc.title)}
-              {#if item.doc.meta?.isProtected}
-                <Lock size={14} class="shrink-0 text-muted-foreground ml-auto" />
+              <span class="truncate">{@html renderInlineCode(item.doc.title)}</span>
+              {#if badges.length > 0 || item.doc.meta?.isProtected}
+                <span class="ml-auto flex items-center gap-1 shrink-0">
+                  {#each badges as badge (badge.text)}
+                    <SidebarBadge {badge} />
+                  {/each}
+                  {#if item.doc.meta?.isProtected}
+                    <Lock size={14} class="text-muted-foreground" />
+                  {/if}
+                </span>
               {/if}
             </a>
           {/if}
@@ -360,19 +390,27 @@
     {#each sortedStandalone as doc (doc.slug)}
       {@const href = `${docsBase}/${doc.slug}`}
       {@const isActive = pathname === href}
+      {@const badges = resolveBadges(doc.meta?.badge)}
       <a
         {href}
         onclick={onLinkClick}
-        class="flex items-center gap-2 px-3 py-2 text-sm rounded-xl transition-all {isActive
+        class="flex items-center gap-2 min-w-0 px-3 py-2 text-sm rounded-xl transition-all {isActive
           ? 'bg-primary/10 text-primary font-medium'
           : 'text-foreground hover:text-foreground hover:bg-accent/50'}"
       >
         {#if doc.meta?.icon}
           <Icon icon={doc.meta.icon} size={16} className="shrink-0" />
         {/if}
-        {@html renderInlineCode(doc.title)}
-        {#if doc.meta?.isProtected}
-          <Lock size={14} class="shrink-0 text-muted-foreground ml-auto" />
+        <span class="truncate">{@html renderInlineCode(doc.title)}</span>
+        {#if badges.length > 0 || doc.meta?.isProtected}
+          <span class="ml-auto flex items-center gap-1 shrink-0">
+            {#each badges as badge (badge.text)}
+              <SidebarBadge {badge} />
+            {/each}
+            {#if doc.meta?.isProtected}
+              <Lock size={14} class="text-muted-foreground" />
+            {/if}
+          </span>
         {/if}
       </a>
     {/each}

package/dist/components/docs/SidebarMenuItems.svelte.d.ts

@@ -1,4 +1,5 @@
 import type { SpecraConfig } from '../../config.types.js';
+import { type BadgeInput } from '../../badges.js';
 interface DocItem {
     title: string;
     slug: string;
@@ -13,11 +14,13 @@ interface DocItem {
     categoryCollapsed?: boolean;
     categoryIcon?: string;
     categoryTabGroup?: string;
+    categoryBadge?: BadgeInput;
     meta?: {
         icon?: string;
         tab_group?: string;
         sidebar_position?: number;
         order?: number;
+        badge?: BadgeInput;
         [key: string]: any;
     };
 }

package/dist/components/docs/Update.svelte

@@ -0,0 +1,75 @@
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import { getChangelogContext } from '../../changelog-context.js';
+
+  interface Props {
+    /** Date or release name. Anchors the entry and names it in the ToC. */
+    label?: string;
+    /** Slug of `label`, injected server-side by rehype-changelog-ids. */
+    id?: string;
+    /** Secondary line, typically a version. */
+    description?: string;
+    tags?: string[];
+    /** Overrides the RSS entry. Consumed server-side; unused when rendering. */
+    rss?: { title?: string; description?: string };
+    children?: Snippet;
+  }
+
+  let { label, id, description, tags = [], children }: Props = $props();
+
+  // Absent outside a <Changelog>, in which case nothing filters this update.
+  const changelog = getChangelogContext();
+
+  // Reads the parent's selected-tag state, so toggling a filter re-renders.
+  let visible = $derived(changelog ? changelog.matches(tags) : true);
+</script>
+
+{#if visible}
+  <div
+    {id}
+    class="specra-update grid gap-x-8 gap-y-3 pb-12 scroll-mt-24 last:pb-0 md:grid-cols-[10rem_minmax(0,1fr)]"
+  >
+    <div class="md:sticky md:top-24 md:self-start md:text-right">
+      {#if label}
+        {#if id}
+          <a
+            href="#{id}"
+            class="text-sm font-semibold text-foreground transition-colors hover:text-primary"
+          >
+            {label}
+          </a>
+        {:else}
+          <span class="text-sm font-semibold text-foreground">{label}</span>
+        {/if}
+      {/if}
+
+      {#if description}
+        <div class="mt-1 text-xs text-muted-foreground">{description}</div>
+      {/if}
+
+      {#if tags.length > 0}
+        <div class="mt-2 flex flex-wrap gap-1 md:justify-end">
+          {#each tags as tag (tag)}
+            <span
+              class="rounded-full bg-muted px-1.5 py-0.5 text-[10px] font-medium leading-none text-muted-foreground"
+            >
+              {tag}
+            </span>
+          {/each}
+        </div>
+      {/if}
+    </div>
+
+    <div class="relative border-l border-border pl-8">
+      <span
+        aria-hidden="true"
+        class="absolute -left-[4.5px] top-2 h-2 w-2 rounded-full bg-border ring-4 ring-background"
+      ></span>
+      <div class="prose prose-sm dark:prose-invert max-w-none [&>*:last-child]:mb-0">
+        {#if children}
+          {@render children()}
+        {/if}
+      </div>
+    </div>
+  </div>
+{/if}

package/dist/components/docs/Update.svelte.d.ts

@@ -0,0 +1,19 @@
+import type { Snippet } from 'svelte';
+interface Props {
+    /** Date or release name. Anchors the entry and names it in the ToC. */
+    label?: string;
+    /** Slug of `label`, injected server-side by rehype-changelog-ids. */
+    id?: string;
+    /** Secondary line, typically a version. */
+    description?: string;
+    tags?: string[];
+    /** Overrides the RSS entry. Consumed server-side; unused when rendering. */
+    rss?: {
+        title?: string;
+        description?: string;
+    };
+    children?: Snippet;
+}
+declare const Update: import("svelte").Component<Props, {}, "">;
+type Update = ReturnType<typeof Update>;
+export default Update;

package/dist/components/docs/index.d.ts

@@ -37,7 +37,10 @@ export { default as MobileSidebarWrapper } from './MobileSidebarWrapper.svelte';
 export { default as NotFoundContent } from './NotFoundContent.svelte';
 export { default as SearchHighlight } from './SearchHighlight.svelte';
 export { default as SearchModal } from './SearchModal.svelte';
+export { default as Changelog } from './Changelog.svelte';
+export { default as Update } from './Update.svelte';
 export { default as Sidebar } from './Sidebar.svelte';
+export { default as SidebarBadge } from './SidebarBadge.svelte';
 export { default as SidebarMenuItems } from './SidebarMenuItems.svelte';
 export { default as SidebarSkeleton } from './SidebarSkeleton.svelte';
 export { default as SiteBanner } from './SiteBanner.svelte';

package/dist/components/docs/index.js

@@ -38,7 +38,10 @@ export { default as MobileSidebarWrapper } from './MobileSidebarWrapper.svelte';
 export { default as NotFoundContent } from './NotFoundContent.svelte';
 export { default as SearchHighlight } from './SearchHighlight.svelte';
 export { default as SearchModal } from './SearchModal.svelte';
+export { default as Changelog } from './Changelog.svelte';
+export { default as Update } from './Update.svelte';
 export { default as Sidebar } from './Sidebar.svelte';
+export { default as SidebarBadge } from './SidebarBadge.svelte';
 export { default as SidebarMenuItems } from './SidebarMenuItems.svelte';
 export { default as SidebarSkeleton } from './SidebarSkeleton.svelte';
 export { default as SiteBanner } from './SiteBanner.svelte';

package/dist/index.d.ts

@@ -14,6 +14,9 @@ export * from './utils.js';
 export * from './links.js';
 export * from './inline.js';
 export * from './sidebar-utils.js';
+export * from './badges.js';
+export * from './changelog.js';
+export * from './changelog-context.js';
 export * from './category.js';
 export * from './redirects.js';
 export * from './dev-utils.js';

package/dist/index.js

@@ -18,6 +18,9 @@ export * from './utils.js';
 export * from './links.js';
 export * from './inline.js';
 export * from './sidebar-utils.js';
+export * from './badges.js';
+export * from './changelog.js';
+export * from './changelog-context.js';
 export * from './category.js';
 export * from './redirects.js';
 export * from './dev-utils.js';

package/dist/mdx-components.d.ts

@@ -14,8 +14,8 @@
  * ```
  */
 import type { Component } from 'svelte';
-import { Callout, Accordion, AccordionItem, Tabs, Tab, Image, Video, Card, CardGrid, ImageCard, ImageCardGrid, Steps, Step, Icon, Mermaid, Math, Columns, Column, DocBadge, Tooltip, Frame, CodeBlock, Timeline, TimelineItem, ApiEndpoint, ApiParams, ApiResponse, ApiPlayground, ApiReference } from './components/docs';
-export { Callout, Accordion, AccordionItem, Tabs, Tab, Image, Video, Card, CardGrid, ImageCard, ImageCardGrid, Steps, Step, Icon, Mermaid, Math, Columns, Column, DocBadge, Tooltip, Frame, CodeBlock, Timeline, TimelineItem, ApiEndpoint, ApiParams, ApiResponse, ApiPlayground, ApiReference, };
+import { Callout, Accordion, AccordionItem, Tabs, Tab, Image, Video, Card, CardGrid, ImageCard, ImageCardGrid, Steps, Step, Icon, Mermaid, Math, Columns, Column, DocBadge, Tooltip, Frame, CodeBlock, Timeline, TimelineItem, ApiEndpoint, ApiParams, ApiResponse, ApiPlayground, ApiReference, Changelog, Update } from './components/docs';
+export { Callout, Accordion, AccordionItem, Tabs, Tab, Image, Video, Card, CardGrid, ImageCard, ImageCardGrid, Steps, Step, Icon, Mermaid, Math, Columns, Column, DocBadge, Tooltip, Frame, CodeBlock, Timeline, TimelineItem, ApiEndpoint, ApiParams, ApiResponse, ApiPlayground, ApiReference, Changelog, Update, };
 /**
  * Component map for passing to layout components that render MDX content.
  */

package/dist/mdx-components.js

@@ -13,9 +13,9 @@
  * <Callout type="info">This is a callout</Callout>
  * ```
  */
-import { Callout, Accordion, AccordionItem, Tabs, Tab, Image, Video, Card, CardGrid, ImageCard, ImageCardGrid, Steps, Step, Icon, Mermaid, Math, Columns, Column, DocBadge, Tooltip, Frame, CodeBlock, Timeline, TimelineItem, ApiEndpoint, ApiParams, ApiResponse, ApiPlayground, ApiReference, } from './components/docs';
+import { Callout, Accordion, AccordionItem, Tabs, Tab, Image, Video, Card, CardGrid, ImageCard, ImageCardGrid, Steps, Step, Icon, Mermaid, Math, Columns, Column, DocBadge, Tooltip, Frame, CodeBlock, Timeline, TimelineItem, ApiEndpoint, ApiParams, ApiResponse, ApiPlayground, ApiReference, Changelog, Update, } from './components/docs';
 // Re-export all MDX-usable components
-export { Callout, Accordion, AccordionItem, Tabs, Tab, Image, Video, Card, CardGrid, ImageCard, ImageCardGrid, Steps, Step, Icon, Mermaid, Math, Columns, Column, DocBadge, Tooltip, Frame, CodeBlock, Timeline, TimelineItem, ApiEndpoint, ApiParams, ApiResponse, ApiPlayground, ApiReference, };
+export { Callout, Accordion, AccordionItem, Tabs, Tab, Image, Video, Card, CardGrid, ImageCard, ImageCardGrid, Steps, Step, Icon, Mermaid, Math, Columns, Column, DocBadge, Tooltip, Frame, CodeBlock, Timeline, TimelineItem, ApiEndpoint, ApiParams, ApiResponse, ApiPlayground, ApiReference, Changelog, Update, };
 /**
  * Component map for passing to layout components that render MDX content.
  */
@@ -50,4 +50,6 @@ export const mdxComponents = {
     ApiResponse,
     ApiPlayground,
     ApiReference,
+    Changelog,
+    Update,
 };

package/dist/mdx.d.ts

@@ -1,3 +1,4 @@
+import type { BadgeInput } from "./badges";
 import type { I18nConfig } from "./config.types";
 /**
  * Structured node type for MDX content rendering.
@@ -12,6 +13,7 @@ export interface MdxNode {
     props?: Record<string, any>;
     children?: MdxNode[];
 }
+export declare function processMarkdownToMdxNodes(markdown: string): Promise<MdxNode[]>;
 export interface DocMeta {
     title: string;
     description?: string;
@@ -34,6 +36,8 @@ export interface DocMeta {
     word_count?: number;
     icon?: string;
     tab_group?: string;
+    badge?: BadgeInput;
+    rss?: boolean;
     locale?: string;
     protected?: boolean;
     isProtected?: boolean;
@@ -51,6 +55,7 @@ export interface Doc {
     categoryCollapsed?: boolean;
     categoryIcon?: string;
     categoryTabGroup?: string;
+    categoryBadge?: BadgeInput;
     locale?: string;
 }
 export interface TocItem {

package/dist/mdx.js

@@ -3,6 +3,8 @@ import path from "path";
 import matter from "gray-matter";
 import yaml from "js-yaml";
 import { rehypeBasePath } from "./rehype-base-path.js";
+import { rehypeChangelogIds } from "./rehype-changelog-ids.js";
+import { annotateChangelogNodes } from "./changelog.js";
 import { remarkCodeMeta } from "./remark-code-meta.js";
 import { unified } from "unified";
 import remarkParse from "remark-parse";
@@ -10,6 +12,7 @@ import remarkGfm from "remark-gfm";
 import remarkMath from "remark-math";
 import remarkRehype from "remark-rehype";
 import rehypeSlug from "rehype-slug";
+import GithubSlugger from "github-slugger";
 import rehypeRaw from "rehype-raw";
 import rehypeKatex from "rehype-katex";
 import rehypeStringify from "rehype-stringify";
@@ -66,6 +69,8 @@ const COMPONENT_TAG_MAP = {
     apiresponse: 'ApiResponse',
     apiplayground: 'ApiPlayground',
     apireference: 'ApiReference',
+    changelog: 'Changelog',
+    update: 'Update',
 };
 /**
  * Map of lowercased attribute names to their correct camelCase form.
@@ -170,11 +175,92 @@ function maskInlineCodePipes(markdown) {
     }).join('');
 }
 /**
- * Restore `PIPE_MARKER` back to `|` in a string. No-op if the marker
- * isn't present (the common case), so cheap to call blanket.
+ * Private Use Area characters used to mask `<` and `>` written inside code
+ * (inline spans or fenced blocks) that sits within a component block.
+ *
+ * Why: `ensureComponentBlockIntegrity` deliberately collapses blank lines so
+ * that an entire `<Callout>…</Callout>` stays one CommonMark HTML block. But
+ * inside an HTML block, markdown no longer applies — code spans and fences stop
+ * being code — so a documented tag such as
+ *   An inline `<script src="/x.js">` tag.
+ * is handed to rehype-raw as *real HTML*. parse5 opens a raw-text `<script>`
+ * element that is never closed and swallows every following sibling, so the
+ * next heading silently disappears from the page and its ToC link 404s.
+ *
+ * Masking the angle brackets before remark sees them keeps the block inert for
+ * parse5, and `restoreCodeMarkers` puts them back after the component's
+ * children have been re-parsed as markdown. PUA chars pass through
+ * remark/rehype unchanged and are never HTML-escaped — same trick as
+ * `PIPE_MARKER` above.
+ */
+const LT_MARKER = '';
+const GT_MARKER = '';
+/**
+ * Mask `<` and `>` inside fenced code blocks and single-line inline code spans.
+ * Applied only to the interior of component blocks, where markdown code markers
+ * lose their meaning. Component tags themselves live outside code and are left
+ * alone, so `<Callout>` still parses as a component.
+ */
+function maskCodeAngleBrackets(markdown) {
+    const maskAngles = (s) => s.replace(/</g, LT_MARKER).replace(/>/g, GT_MARKER);
+    return splitByCodeFences(markdown).map(({ text, isCode }) => {
+        if (isCode)
+            return maskAngles(text);
+        let result = '';
+        let i = 0;
+        while (i < text.length) {
+            if (text[i] !== '`') {
+                result += text[i];
+                i++;
+                continue;
+            }
+            let openLen = 0;
+            while (i + openLen < text.length && text[i + openLen] === '`')
+                openLen++;
+            let j = i + openLen;
+            let closeIdx = -1;
+            while (j < text.length && text[j] !== '\n') {
+                if (text[j] === '`') {
+                    let closeLen = 0;
+                    while (j + closeLen < text.length && text[j + closeLen] === '`')
+                        closeLen++;
+                    if (closeLen === openLen) {
+                        closeIdx = j;
+                        break;
+                    }
+                    j += closeLen;
+                }
+                else {
+                    j++;
+                }
+            }
+            if (closeIdx === -1) {
+                result += text.slice(i, i + openLen);
+                i += openLen;
+            }
+            else {
+                const content = maskAngles(text.slice(i + openLen, closeIdx));
+                result += text.slice(i, i + openLen) + content + text.slice(closeIdx, closeIdx + openLen);
+                i = closeIdx + openLen;
+            }
+        }
+        return result;
+    }).join('');
+}
+/**
+ * Restore `PIPE_MARKER` back to `|`, and `LT_MARKER`/`GT_MARKER` back to
+ * `<`/`>`, in a string. No-op if no marker is present (the common case), so
+ * cheap to call blanket.
  */
 function restorePipeMarkers(s) {
-    return s.indexOf(PIPE_MARKER) === -1 ? s : s.split(PIPE_MARKER).join('|');
+    let out = s;
+    if (out.indexOf(PIPE_MARKER) !== -1)
+        out = out.split(PIPE_MARKER).join('|');
+    if (out.indexOf(LT_MARKER) !== -1)
+        out = out.split(LT_MARKER).join('<');
+    if (out.indexOf(GT_MARKER) !== -1)
+        out = out.split(GT_MARKER).join('>');
+    return out;
 }
 /**
  * Walk an MdxNode tree and restore `PIPE_MARKER` to `|` in every string
@@ -1168,7 +1254,14 @@ function ensureComponentBlockIntegrity(markdown) {
         // code fences. The code fence content is raw text inside the HTML block and
         // will be re-processed by processComponentChildren through the markdown
         // pipeline, which restores proper code formatting.
-        const collapsed = block.replace(/^\s*$/gm, '<!-- -->');
+        // Mask `<`/`>` written inside code (inline spans and fences) BEFORE the
+        // blank-line collapse turns this whole block into one raw HTML block.
+        // Once it is raw HTML, markdown code markers no longer protect their
+        // contents, and a documented tag like `<script src="...">` reaches parse5
+        // as real HTML — a raw-text element that never closes and swallows every
+        // sibling after the component, heading and all. Restored by
+        // `restorePipeMarkers` once the children are re-parsed as markdown.
+        const collapsed = maskCodeAngleBrackets(block).replace(/^\s*$/gm, '<!-- -->');
         result += markdown.slice(lastIndex, blockStart) + collapsed;
         lastIndex = blockEnd;
         openTagRegex.lastIndex = blockEnd;
@@ -1179,7 +1272,7 @@ function ensureComponentBlockIntegrity(markdown) {
     }
     return markdown;
 }
-async function processMarkdownToMdxNodes(markdown) {
+export async function processMarkdownToMdxNodes(markdown) {
     // Mask pipes inside inline code spans so GFM tables containing
     // `{{ x | filter }}`-style code don't get their rows broken.
     const masked = maskInlineCodePipes(markdown);
@@ -1200,6 +1293,9 @@ async function processMarkdownToMdxNodes(markdown) {
         .use(remarkRehype, { allowDangerousHtml: true })
         .use(rehypeRaw)
         .use(rehypeSlug)
+        // After rehypeSlug so the intent is obvious: replay the heading sequence
+        // through a second slugger, then anchor each <Update> in that namespace.
+        .use(rehypeChangelogIds)
         .use(rehypeKatex);
     if (basePath) {
         processor.use(rehypeBasePath, { basePath });
@@ -1210,6 +1306,10 @@ async function processMarkdownToMdxNodes(markdown) {
     const children = hast.children || [];
     const nodes = await hastChildrenToMdxNodes(children);
     restorePipeMarkersInNodes(nodes);
+    // Union each <Changelog>'s child tags into `allTags`. Done here, on the
+    // server, because children render after their parent during SSR — a filter
+    // bar that waited for its updates to self-register would serialize empty.
+    annotateChangelogNodes(nodes);
     return nodes;
 }
 /**
@@ -1477,6 +1577,7 @@ export function getAllDocs(version = "v1.0.0", locale, product) {
                     doc.categoryCollapsed = categoryConfig.collapsed;
                     doc.categoryIcon = categoryConfig.icon;
                     doc.categoryTabGroup = categoryConfig.tab_group;
+                    doc.categoryBadge = categoryConfig.badge;
                 }
             }
             return doc;
@@ -1621,19 +1722,54 @@ export function getAdjacentDocs(currentSlug, allDocs) {
     };
 }
 export function extractTableOfContents(content) {
-    const headingRegex = /^(#{2,3})\s+(.+)$/gm;
+    // One regex over both kinds of anchor so they come back in document order.
+    //   group 1/2 — an ATX heading, at any level (see the slugger note below)
+    //   group 3   — the `label` of an <Update>, which anchors a changelog entry
+    // `[^>]*?` (not `.`) spans newlines, because authors wrap long <Update> tags.
+    const anchorRegex = /^(#{1,6})[ \t]+(.+)$|<update\b[^>]*?\blabel\s*=\s*["']([^"']+)["']/gim;
     const toc = [];
-    let match;
-    while ((match = headingRegex.exec(content)) !== null) {
-        const level = match[1].length;
-        const text = match[2];
-        // Generate ID the same way rehype-slug does
-        const id = text
-            .toLowerCase()
-            .replace(/\s+/g, "-") // Replace spaces with hyphens first
-            .replace(/[^a-z0-9-]/g, "") // Remove special chars (dots, slashes, etc)
-            .replace(/^-|-$/g, ""); // Remove leading/trailing hyphens
-        toc.push({ id, title: text, level });
+    // Mirror rehype-slug exactly: it builds ONE GithubSlugger per document and
+    // slugs every h1–h6 in order, so a repeated heading renders as `setup` and
+    // then `setup-1`. github-slugger's bare `slug()` export is stateless and
+    // cannot know that, so it emitted `setup` twice and the second ToC link
+    // silently scrolled to the first heading.
+    //
+    // The slugger must see headings the ToC never displays (h1, h4–h6) because
+    // they still consume names from the same namespace — `# Setup` followed by
+    // `## Setup` renders the h2 as `setup-1`.
+    //
+    // <Update> labels share this slugger too, mirroring rehype-changelog-ids.ts,
+    // so a label can never collide with a heading of the same text.
+    const slugger = new GithubSlugger();
+    // Headings inside fenced code blocks are code, not headings. They get no
+    // `id` in the rendered page, so a ToC entry for them can only ever 404 —
+    // and rehype-slug never sees them either, so skipping them keeps the two
+    // sluggers in lockstep. The same reasoning covers a fenced <Update> example.
+    for (const { text: segment, isCode } of splitByCodeFences(content)) {
+        if (isCode)
+            continue;
+        let match;
+        anchorRegex.lastIndex = 0;
+        while ((match = anchorRegex.exec(segment)) !== null) {
+            const [, hashes, headingText, updateLabel] = match;
+            if (updateLabel !== undefined) {
+                const label = updateLabel.trim();
+                if (!label)
+                    continue;
+                // Updates sit at the ToC's top level, alongside h2s.
+                toc.push({ id: slugger.slug(label), title: label, level: 2 });
+                continue;
+            }
+            const level = hashes.length;
+            const text = headingText.trim();
+            // Backticks are stripped first because rehype-slug slugs the RENDERED
+            // heading text, where `code` markup is already gone. Always slug, even
+            // for levels we drop, to keep the occurrence counters aligned.
+            const id = slugger.slug(text.replace(/`/g, ""));
+            if (level < 2 || level > 3)
+                continue;
+            toc.push({ id, title: text, level });
+        }
     }
     return toc;
 }

package/dist/rehype-changelog-ids.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Rehype plugin that gives every `<Update>` a stable anchor id.
+ *
+ * The id is slugged from the update's `label`, using a slugger that has ALSO
+ * consumed every heading on the page. rehype-slug builds one GithubSlugger per
+ * document and feeds it every h1–h6 in order; by replaying that same sequence
+ * here we land in the same namespace. Two consequences:
+ *
+ *   - An `<Update label="Changelog">` on a page that also has `## Changelog`
+ *     becomes `changelog-1` instead of silently duplicating the heading's id.
+ *   - Two updates sharing a label get `v1` and `v1-1`, never a collision.
+ *
+ * `extractTableOfContents` performs the same walk over the raw markdown, so the
+ * anchors it links to are byte-identical to the ones rendered here.
+ *
+ * Manually walks the tree to avoid ESM/CJS issues with unist-util-visit, matching
+ * rehype-base-path.ts.
+ */
+import type { Root } from 'hast';
+export declare function rehypeChangelogIds(): (tree: Root) => void;