specra 0.2.67 → 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,7 +12,7 @@ import remarkGfm from "remark-gfm";
 import remarkMath from "remark-math";
 import remarkRehype from "remark-rehype";
 import rehypeSlug from "rehype-slug";
-import { slug as githubSlug } from "github-slugger";
+import GithubSlugger from "github-slugger";
 import rehypeRaw from "rehype-raw";
 import rehypeKatex from "rehype-katex";
 import rehypeStringify from "rehype-stringify";
@@ -67,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.
@@ -1268,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);
@@ -1289,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 });
@@ -1299,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;
 }
 /**
@@ -1566,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;
@@ -1710,26 +1722,52 @@ 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 = [];
+    // 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.
+    // `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;
-        headingRegex.lastIndex = 0;
-        while ((match = headingRegex.exec(segment)) !== null) {
-            const level = match[1].length;
-            const text = match[2];
-            // Use the SAME slugger rehype-slug uses, rather than approximating it.
-            // The old hand-rolled version stripped `_` and trimmed a trailing `-`,
-            // while github-slugger keeps both — so every heading naming a snake_case
-            // identifier (`list_display`, `on_upload`, `cache_page`) produced a ToC
-            // link that pointed at nothing. Backticks are stripped first because
-            // rehype-slug slugs the RENDERED heading text, where `code` markup is
-            // already gone.
-            const id = githubSlug(text.replace(/`/g, ""));
+        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 });
         }
     }

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;

package/dist/rehype-changelog-ids.js

@@ -0,0 +1,43 @@
+import GithubSlugger from 'github-slugger';
+const HEADING_TAG = /^h[1-6]$/;
+/** Concatenate the text nodes beneath a node, as hast-util-to-string would. */
+function textContent(node) {
+    if (node.type === 'text')
+        return String(node.value ?? '');
+    if (Array.isArray(node.children))
+        return node.children.map(textContent).join('');
+    return '';
+}
+/** Preorder walk over element nodes, i.e. document order. */
+function walkElements(nodes, fn) {
+    for (const node of nodes) {
+        if (node.type !== 'element')
+            continue;
+        fn(node);
+        if (node.children) {
+            walkElements(node.children, fn);
+        }
+    }
+}
+export function rehypeChangelogIds() {
+    return (tree) => {
+        const slugger = new GithubSlugger();
+        walkElements(tree.children, (node) => {
+            // Consume the name rehype-slug already consumed for this heading, keeping
+            // the two occurrence counters aligned. The return value is discarded —
+            // rehype-slug owns the heading's actual id.
+            if (HEADING_TAG.test(node.tagName)) {
+                slugger.slug(textContent(node));
+                return;
+            }
+            if (node.tagName !== 'update')
+                return;
+            const label = node.properties?.label;
+            // A label-less update has no identity to anchor. It still renders; it just
+            // gets no anchor, no ToC entry and no feed item.
+            if (typeof label !== 'string' || !label.trim())
+                return;
+            node.properties = { ...node.properties, id: slugger.slug(label.trim()) };
+        });
+    };
+}

package/dist/sidebar-utils.d.ts

@@ -3,10 +3,12 @@
  * This module provides consistent sidebar logic across the application
  * to ensure ordering is handled the same way everywhere.
  */
+import type { BadgeInput } from "./badges.js";
 export interface SidebarGroup {
     label: string;
     path: string;
     icon?: string;
+    badge?: BadgeInput;
     items: any[];
     position: number;
     collapsible: boolean;
@@ -50,6 +52,7 @@ export declare function buildSidebarStructure<T extends {
     categoryLabel?: string;
     categoryPosition?: number;
     categoryIcon?: string;
+    categoryBadge?: BadgeInput;
     categoryCollapsible?: boolean;
     categoryCollapsed?: boolean;
     meta: any;

package/dist/sidebar-utils.js

@@ -49,11 +49,14 @@ export function buildSidebarStructure(docs) {
     docs.forEach((doc) => {
         const pathParts = doc.filePath.split("/");
         const folderPath = pathParts.length > 1 ? pathParts.slice(0, -1).join("/") : "";
-        if (folderPath && doc.categoryLabel) {
+        // A `_category_.json` may set a badge without setting a label, so keying
+        // this purely off `categoryLabel` would silently drop the badge.
+        if (folderPath && (doc.categoryLabel || doc.categoryBadge)) {
             categoryMetadata.set(folderPath, {
                 label: doc.categoryLabel,
                 position: doc.categoryPosition,
                 icon: doc.categoryIcon,
+                badge: doc.categoryBadge,
                 collapsible: doc.categoryCollapsible,
                 collapsed: doc.categoryCollapsed
             });
@@ -100,6 +103,7 @@ export function buildSidebarStructure(docs) {
                         label: metadata?.label ?? folderLabel,
                         path: currentPath,
                         icon: metadata?.icon,
+                        badge: metadata?.badge,
                         items: [],
                         position: metadata?.position ?? 999,
                         collapsible: metadata?.collapsible ?? true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specra",
-  "version": "0.2.67",
+  "version": "0.2.68",
   "description": "A modern documentation library for SvelteKit with built-in versioning, API reference generation, full-text search, and MDX support",
   "svelte": "./dist/index.js",
   "types": "./dist/index.d.ts",