svelte-docsmith 0.7.0 → 0.9.0

package/dist/components/markdown/pre.svelte

@@ -6,18 +6,102 @@
 
 	const clipboard = useClipboard();
 
-	const { children }: { children: Snippet } = $props();
+	const {
+		title,
+		lineNumbers = false,
+		startLine = 1,
+		children
+	}: {
+		/** Filename or caption, from the fence's `title=` metadata. */
+		title?: string;
+		/** Number the lines, from `showLineNumbers`. */
+		lineNumbers?: boolean;
+		/** First line's number, from `startLine=`. */
+		startLine?: number;
+		children: Snippet;
+	} = $props();
+
+	/**
+	 * Twoslash popups are absolutely positioned inside the code block, which is a
+	 * scroll container, so anything reaching past its edges is clipped: a hover
+	 * near the last line shows a sliver of the type and nothing else. CSS can't
+	 * fix this, because a horizontally scrolling element must also clip
+	 * vertically. So on hover the popup is promoted to fixed positioning, whose
+	 * containing block is the viewport rather than the scroller.
+	 *
+	 * Without JavaScript the popup still opens on hover, clipped as before, so
+	 * this only ever improves on the CSS-only behaviour.
+	 */
+	function unclipPopups(node: HTMLElement) {
+		const GAP = 6;
+
+		const place = (event: Event) => {
+			const target = event.target as HTMLElement | null;
+			const trigger = target?.closest?.('.twoslash-hover') as HTMLElement | null;
+			if (!trigger) return;
+			const popup = trigger.querySelector('.twoslash-popup-container') as HTMLElement | null;
+			if (!popup) return;
+
+			// Measure while visible but before committing a position, so the popup's
+			// own width decides whether it flips to stay on screen.
+			popup.style.position = 'fixed';
+			popup.style.left = '0px';
+			popup.style.top = '0px';
+			const rect = trigger.getBoundingClientRect();
+			const { width, height } = popup.getBoundingClientRect();
+
+			const left = Math.max(8, Math.min(rect.left, window.innerWidth - width - 8));
+			// Below the token unless that would run off the bottom, then above it.
+			const below = rect.bottom + GAP;
+			const top = below + height > window.innerHeight - 8 ? rect.top - height - GAP : below;
+
+			popup.style.left = `${left}px`;
+			popup.style.top = `${Math.max(8, top)}px`;
+		};
+
+		const reset = (event: Event) => {
+			const trigger = (event.target as HTMLElement | null)?.closest?.(
+				'.twoslash-hover'
+			) as HTMLElement | null;
+			const popup = trigger?.querySelector('.twoslash-popup-container') as HTMLElement | null;
+			if (popup) popup.removeAttribute('style');
+		};
+
+		node.addEventListener('mouseover', place);
+		node.addEventListener('mouseout', reset);
+		return {
+			destroy() {
+				node.removeEventListener('mouseover', place);
+				node.removeEventListener('mouseout', reset);
+			}
+		};
+	}
 </script>
 
-<div class="rounded-md overflow-hidden bg-muted mt-2 shadow-md text-sm relative">
+<div class="rounded-md overflow-hidden bg-muted mt-2 shadow-md text-sm relative" use:unclipPopups>
+	{#if title}
+		<!-- The filename bar doubles as the copy button's row, so the button stops
+		     floating over the first line of code when a title is present. -->
+		<div class="docsmith-code-title">
+			<span class="docsmith-code-title-text">{title}</span>
+			<CopyButton copied={clipboard.copied} onclick={() => clipboard.copy()} class="bg-muted" />
+		</div>
+	{/if}
+
 	<ScrollArea orientation="both" class="relative">
-		<CopyButton
-			copied={clipboard.copied}
-			onclick={() => clipboard.copy()}
-			class="bg-muted absolute top-2 right-2 z-10"
-		/>
+		{#if !title}
+			<CopyButton
+				copied={clipboard.copied}
+				onclick={() => clipboard.copy()}
+				class="bg-muted absolute top-2 right-2 z-10"
+			/>
+		{/if}
 
-		<pre class="not-prose shiki max-h-[32rem] flex shrink" use:clipboard.readText>
+		<pre
+			class="not-prose shiki max-h-[32rem] flex shrink"
+			class:docsmith-line-numbers={lineNumbers}
+			style={lineNumbers && startLine !== 1 ? `--docsmith-line-start: ${startLine - 1}` : undefined}
+			use:clipboard.readText>
 			{@render children()}
 		</pre>
 	</ScrollArea>
@@ -44,6 +128,64 @@
 		padding-inline: 1rem;
 	}
 
+	/* --- Filename bar --- */
+	.docsmith-code-title {
+		display: flex;
+		align-items: center;
+		justify-content: space-between;
+		gap: 0.75rem;
+		padding: 0.4rem 0.5rem 0.4rem 1rem;
+		border-bottom: 1px solid var(--border);
+		background: color-mix(in oklch, var(--muted) 60%, var(--background));
+	}
+	.docsmith-code-title-text {
+		font-family: var(--font-mono, ui-monospace, monospace);
+		font-size: 0.78rem;
+		color: var(--muted-foreground);
+		overflow-wrap: anywhere;
+	}
+
+	/* --- Line numbers ---
+	   A CSS counter on Shiki's existing per-line spans, so numbering adds no DOM
+	   and stays out of the text the copy button reads. `--docsmith-line-start`
+	   offsets the counter for a snippet lifted out of a larger file. */
+	:global(pre.docsmith-line-numbers code) {
+		counter-reset: docsmith-line var(--docsmith-line-start, 0);
+	}
+	:global(pre.docsmith-line-numbers span.line) {
+		counter-increment: docsmith-line;
+		position: relative;
+		padding-inline-start: 3.2rem;
+	}
+	:global(pre.docsmith-line-numbers span.line::before) {
+		content: counter(docsmith-line);
+		position: absolute;
+		left: 0;
+		width: 2.4rem;
+		text-align: right;
+		color: color-mix(in oklch, var(--muted-foreground) 65%, transparent);
+		/* Numbers are decoration, not content: keep them out of selections and
+		   off the clipboard. */
+		user-select: none;
+	}
+	/* The diff gutter glyph would collide with the number, so shift it over. */
+	:global(pre.docsmith-line-numbers span.line.diff::before) {
+		content: counter(docsmith-line);
+	}
+	:global(pre.docsmith-line-numbers span.line.diff::after) {
+		position: absolute;
+		left: 2.7rem;
+		font-weight: 600;
+	}
+	:global(pre.docsmith-line-numbers span.line.diff.add::after) {
+		content: '+';
+		color: oklch(0.6 0.15 150);
+	}
+	:global(pre.docsmith-line-numbers span.line.diff.remove::after) {
+		content: '−';
+		color: oklch(0.58 0.19 25);
+	}
+
 	/* Two tiers of annotation. EMPHASIS (highlight, word) tints with the theme's
 	   --primary, so it reads as the brand pointing at a line and recolors with
 	   the active theme. SEMANTIC (diff, error, warning) uses fixed OKLCH hues so
@@ -125,6 +267,94 @@
 		}
 	}
 
+	/* --- Twoslash hovers ---
+	   Restyled from @shikijs/twoslash's rich theme onto our tokens so the popup
+	   belongs to the site in both colour schemes. Underline marks a token as
+	   inspectable; the popup is a hidden sibling revealed on hover. `unclipPopups`
+	   then promotes it to fixed positioning so the code block's scrolling does not
+	   clip it — see the comment there. */
+	:global(pre .twoslash-hover) {
+		position: relative;
+		border-bottom: 1px dotted color-mix(in oklch, var(--muted-foreground) 55%, transparent);
+	}
+	:global(pre .twoslash-popup-container) {
+		position: absolute;
+		z-index: 40;
+		display: none;
+		left: 0;
+		top: 1.6em;
+		/* Shrink to the type's own width so a short signature isn't a wide slab;
+		   the script measures this before choosing a position. */
+		width: max-content;
+		max-width: min(32rem, 78vw);
+		padding: 0.5rem 0.7rem;
+		border: 1px solid var(--border);
+		border-radius: var(--radius, 0.5rem);
+		background: var(--popover, var(--card));
+		color: var(--popover-foreground, var(--foreground));
+		box-shadow: 0 8px 24px rgb(0 0 0 / 0.18);
+		white-space: pre-wrap;
+		text-align: left;
+		font-size: 0.85em;
+		line-height: 1.5;
+	}
+	:global(pre .twoslash-hover:hover .twoslash-popup-container) {
+		display: block;
+	}
+	/* The signature keeps Shiki's own colours and monospace. */
+	:global(pre .twoslash-popup-code) {
+		display: block;
+		font-family: var(--font-mono, ui-monospace, monospace);
+		white-space: pre-wrap;
+	}
+
+	/* Prose, by contrast, is prose. Inside a <pre> it would otherwise inherit
+	   monospace and whatever token colour the hovered span happened to carry,
+	   which reads as more code rather than an explanation of it. */
+	:global(pre .twoslash-popup-docs) {
+		/* The dark-theme swap repaints every span inside `.shiki` with
+		   `--shiki-dark`, which these spans inherit from whichever token was
+		   hovered — so docs took on the colour of the word above them. Redefining
+		   the variable here resolves it to prose colours instead of fighting an
+		   `!important` rule. */
+		--shiki-dark: var(--muted-foreground);
+		margin-top: 0.5rem;
+		padding-top: 0.5rem;
+		border-top: 1px solid var(--border);
+		font-family: var(--font-sans, ui-sans-serif, system-ui, sans-serif);
+		font-size: 0.92em;
+		line-height: 1.55;
+		color: var(--muted-foreground);
+		white-space: normal;
+	}
+
+	/* Each @param is its own line: the tags are inline spans, so without this
+	   they run together into one paragraph. */
+	:global(pre .twoslash-popup-docs-tags) {
+		display: flex;
+		flex-direction: column;
+		gap: 0.35rem;
+	}
+	:global(pre .twoslash-popup-docs-tag) {
+		display: block;
+	}
+	:global(pre .twoslash-popup-docs-tag-value) {
+		--shiki-dark: var(--muted-foreground);
+		color: var(--muted-foreground);
+	}
+	/* And the tag name needs a gap, or it reads as "@paramcallbackfn". */
+	:global(pre .twoslash-popup-docs-tag-name) {
+		--shiki-dark: var(--primary);
+		margin-right: 0.4em;
+		font-family: var(--font-mono, ui-monospace, monospace);
+		font-size: 0.92em;
+		color: var(--primary);
+	}
+	/* A snippet that deliberately shows an error (// @errors:) marks the line. */
+	:global(pre .twoslash-error) {
+		background: color-mix(in oklch, oklch(0.62 0.2 25) 14%, transparent);
+	}
+
 	/* --- Word highlight (// [!code word:name]): a primary-tinted inline pill --- */
 	:global(pre .highlighted-word) {
 		border-radius: 0.3rem;

package/dist/components/markdown/pre.svelte.d.ts

@@ -1,5 +1,11 @@
 import type { Snippet } from 'svelte';
 type $$ComponentProps = {
+    /** Filename or caption, from the fence's `title=` metadata. */
+    title?: string;
+    /** Number the lines, from `showLineNumbers`. */
+    lineNumbers?: boolean;
+    /** First line's number, from `startLine=`. */
+    startLine?: number;
     children: Snippet;
 };
 declare const Pre: import("svelte").Component<$$ComponentProps, {}, "">;

package/dist/core/changelog.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The record types for the generated changelog index. The `docsmith()` Vite
+ * plugin parses your package's `CHANGELOG.md` at build time and emits these as
+ * the `svelte-docsmith/changelog` virtual module, so every release becomes a
+ * page and a feed entry without being written twice.
+ */
+/** One group of changes within a release, e.g. "Minor Changes". */
+export type ChangelogGroup = {
+    /** The group heading as written, e.g. `Minor Changes` or `Patch Changes`. */
+    kind: string;
+    /**
+     * Each entry's body as HTML, rendered from markdown at build time with the
+     * changeset's commit hash removed. HTML rather than markdown so a consuming
+     * site needs no runtime renderer.
+     */
+    items: string[];
+};
+/** One released version. */
+export type ChangelogRelease = {
+    /** Version string as it appears in the changelog, e.g. `0.8.0`. */
+    version: string;
+    /** Release date (ISO) from the git history, when it can be determined. */
+    date?: string;
+    groups: ChangelogGroup[];
+    /**
+     * A hand-written page for this release, when `src/routes/changelog/<version>/`
+     * exists. The generated entry is the fallback, so a release that deserves a
+     * proper write-up can have one without the rest going undocumented.
+     */
+    path?: string;
+};

package/dist/core/changelog.js

@@ -0,0 +1,7 @@
+/**
+ * The record types for the generated changelog index. The `docsmith()` Vite
+ * plugin parses your package's `CHANGELOG.md` at build time and emits these as
+ * the `svelte-docsmith/changelog` virtual module, so every release becomes a
+ * page and a feed entry without being written twice.
+ */
+export {};

package/dist/core/config.d.ts

@@ -14,6 +14,25 @@ export type DocsmithFooterColumn = {
     title: string;
     links: DocsmithLink[];
 };
+/** A thin announcement bar shown at the top of every page. */
+export type DocsmithAnnouncement = {
+    /** The message text. */
+    text: string;
+    /** Optional leading pill label, e.g. `'New'`, `'Beta'`, or a version. */
+    tag?: string;
+    /** Optional link the bar points to. */
+    href?: string;
+    /** Open the link in a new tab with `rel="noopener"`. */
+    external?: boolean;
+    /**
+     * Dismissal key. A dismissed bar stays dismissed until this value changes, so
+     * bump it (or edit `text`) when you post a new announcement. Defaults to the
+     * text itself.
+     */
+    id?: string;
+    /** Let readers dismiss the bar. Defaults to `true`. */
+    dismissible?: boolean;
+};
 export type DocsmithConfig = {
     /** Site title, shown in the header/sidebar and in the `<title>` suffix. */
     title: string;
@@ -42,6 +61,8 @@ export type DocsmithConfig = {
     version?: string;
     /** Optional logo image src; falls back to the built-in book mark. */
     logo?: string;
+    /** Optional announcement bar shown at the top of every page. */
+    announcement?: DocsmithAnnouncement;
     /** Top-level header navigation links. */
     nav?: DocsmithLink[];
     /** Footer content, driven by data. */

package/dist/core/config.js

@@ -23,6 +23,25 @@ export function defineConfig(config) {
             throw new Error(`[svelte-docsmith] config.${key} must be a string when set.`);
         }
     }
+    if (config.announcement !== undefined) {
+        const a = config.announcement;
+        if (typeof a !== 'object' || a === null) {
+            throw new Error('[svelte-docsmith] config.announcement must be an object ({ text, href?, id?, external?, dismissible? }).');
+        }
+        if (typeof a.text !== 'string' || a.text.trim() === '') {
+            throw new Error('[svelte-docsmith] config.announcement.text is required and must be a string.');
+        }
+        for (const key of ['tag', 'href', 'id']) {
+            if (a[key] !== undefined && typeof a[key] !== 'string') {
+                throw new Error(`[svelte-docsmith] config.announcement.${key} must be a string when set.`);
+            }
+        }
+        for (const key of ['external', 'dismissible']) {
+            if (a[key] !== undefined && typeof a[key] !== 'boolean') {
+                throw new Error(`[svelte-docsmith] config.announcement.${key} must be a boolean when set.`);
+            }
+        }
+    }
     if (config.nav !== undefined) {
         if (!Array.isArray(config.nav)) {
             throw new Error('[svelte-docsmith] config.nav must be an array of { label, href } links.');

package/dist/core/content.d.ts

@@ -13,7 +13,12 @@
 export type DocsContentItem = {
     title: string;
     path: string;
-    section?: string;
+    /**
+     * Sidebar group. A string places the page in a single top-level group; an
+     * array names a nested group path (e.g. `['Guides', 'Advanced']`), building
+     * collapsible subsections. Omitted pages fall under "Docs".
+     */
+    section?: string | string[];
     order?: number;
     description?: string;
     /** Source file path relative to the app cwd, for the "Edit this page" link. */

package/dist/core/index.d.ts

@@ -1,3 +1,3 @@
-export { defineConfig, type DocsmithConfig, type DocsmithLink, type DocsmithFooterColumn } from './config.js';
+export { defineConfig, type DocsmithConfig, type DocsmithLink, type DocsmithFooterColumn, type DocsmithAnnouncement } from './config.js';
 export type { DocsContentItem, SearchDoc, LlmsDoc } from './content.js';
-export { navFromContent, type NavItem, type NavGroup } from './nav.js';
+export { navFromContent, flattenNav, navTrail, isNavGroup, type NavItem, type NavGroup, type NavNode } from './nav.js';

package/dist/core/index.js

@@ -3,4 +3,4 @@
 // several of these (e.g. the shell) import from here; the public surface is
 // re-exported through `src/lib/index.ts`.
 export { defineConfig } from './config.js';
-export { navFromContent } from './nav.js';
+export { navFromContent, flattenNav, navTrail, isNavGroup } from './nav.js';

package/dist/core/nav.d.ts

@@ -1,17 +1,34 @@
 import type { DocsContentItem } from './content.js';
-/** A single sidebar link. */
+/** A single sidebar link (a leaf). */
 export type NavItem = {
     title: string;
     url: string;
 };
-/** A titled group of sidebar links. */
+/** A titled group of sidebar entries, which may themselves be nested groups. */
 export type NavGroup = {
     title: string;
-    items: NavItem[];
+    items: NavNode[];
 };
+/** A sidebar entry: either a link or a nested group. */
+export type NavNode = NavItem | NavGroup;
+/** Narrow a {@link NavNode} to a {@link NavGroup} (an entry with children). */
+export declare function isNavGroup(node: NavNode): node is NavGroup;
 /**
- * Derive sidebar nav from a content collection: group by `section`, order by
- * `order` within a group, and order groups by the smallest `order` they
- * contain. Entries without a `section` fall under "Docs".
+ * Derive sidebar nav from a content collection. Each page's `section` (a string
+ * or a nested path) places it in the tree; within every level, entries order by
+ * `order` (then title), and a group inherits the smallest `order` of its
+ * descendants so groups sort by their earliest child. Top-level entries are
+ * always groups; pages without a section fall under "Docs".
  */
 export declare function navFromContent(content: DocsContentItem[]): NavGroup[];
+/**
+ * Flatten the nav tree to its leaf links in sidebar reading order (depth-first),
+ * for the prev/next pager.
+ */
+export declare function flattenNav(nodes: NavNode[]): NavItem[];
+/**
+ * The trail of group titles leading to the page at `url` (top group first,
+ * excluding the page itself), or `undefined` if the page is not in the tree.
+ * Drives the breadcrumb trail.
+ */
+export declare function navTrail(nodes: NavNode[], url: string): string[] | undefined;

package/dist/core/nav.js

@@ -1,22 +1,101 @@
+/** Narrow a {@link NavNode} to a {@link NavGroup} (an entry with children). */
+export function isNavGroup(node) {
+    return 'items' in node;
+}
+/**
+ * Normalize a page's `section` to a group path. A string is a single level; an
+ * array is a nested path; blank or missing sections fall under "Docs". Empty
+ * strings inside an array are dropped so a stray `['Guides', '']` stays sane.
+ */
+function sectionPath(section) {
+    const segs = Array.isArray(section) ? section : section ? [section] : [];
+    const clean = segs.filter((s) => typeof s === 'string' && s.trim() !== '');
+    return clean.length ? clean : ['Docs'];
+}
+function makeBuilder(title) {
+    return { title, order: Infinity, groups: new Map(), leaves: [] };
+}
+/**
+ * Emit a group's children (nested groups and leaf links) as one list, sorted by
+ * `order` and then title. The title tiebreak keeps the output deterministic when
+ * pages share an order (e.g. all default to 0), instead of depending on the
+ * filesystem scan order.
+ */
+function emitItems(node) {
+    const entries = [];
+    for (const leaf of node.leaves) {
+        entries.push({
+            order: leaf.order,
+            title: leaf.title,
+            node: { title: leaf.title, url: leaf.url }
+        });
+    }
+    for (const group of node.groups.values()) {
+        entries.push({
+            order: group.order,
+            title: group.title,
+            node: { title: group.title, items: emitItems(group) }
+        });
+    }
+    entries.sort((a, b) => a.order - b.order || a.title.localeCompare(b.title));
+    return entries.map((e) => e.node);
+}
 /**
- * Derive sidebar nav from a content collection: group by `section`, order by
- * `order` within a group, and order groups by the smallest `order` they
- * contain. Entries without a `section` fall under "Docs".
+ * Derive sidebar nav from a content collection. Each page's `section` (a string
+ * or a nested path) places it in the tree; within every level, entries order by
+ * `order` (then title), and a group inherits the smallest `order` of its
+ * descendants so groups sort by their earliest child. Top-level entries are
+ * always groups; pages without a section fall under "Docs".
  */
 export function navFromContent(content) {
-    const groups = new Map();
+    const root = makeBuilder('');
     for (const item of content) {
-        const section = item.section ?? 'Docs';
         const order = item.order ?? 0;
-        const group = groups.get(section) ?? { minOrder: Infinity, items: [] };
-        group.items.push({ title: item.title, url: item.path, order });
-        group.minOrder = Math.min(group.minOrder, order);
-        groups.set(section, group);
+        let node = root;
+        for (const seg of sectionPath(item.section)) {
+            let child = node.groups.get(seg);
+            if (!child) {
+                child = makeBuilder(seg);
+                node.groups.set(seg, child);
+            }
+            child.order = Math.min(child.order, order);
+            node = child;
+        }
+        node.leaves.push({ title: item.title, url: item.path, order });
+    }
+    // The root only ever holds groups (every page has at least one path segment),
+    // so its emitted items are all NavGroups.
+    return emitItems(root);
+}
+/**
+ * Flatten the nav tree to its leaf links in sidebar reading order (depth-first),
+ * for the prev/next pager.
+ */
+export function flattenNav(nodes) {
+    const out = [];
+    for (const node of nodes) {
+        if (isNavGroup(node))
+            out.push(...flattenNav(node.items));
+        else
+            out.push(node);
+    }
+    return out;
+}
+/**
+ * The trail of group titles leading to the page at `url` (top group first,
+ * excluding the page itself), or `undefined` if the page is not in the tree.
+ * Drives the breadcrumb trail.
+ */
+export function navTrail(nodes, url) {
+    for (const node of nodes) {
+        if (isNavGroup(node)) {
+            const inner = navTrail(node.items, url);
+            if (inner)
+                return [node.title, ...inner];
+        }
+        else if (node.url === url) {
+            return [];
+        }
     }
-    return [...groups.entries()]
-        .sort((a, b) => a[1].minOrder - b[1].minOrder)
-        .map(([title, group]) => ({
-        title,
-        items: group.items.sort((a, b) => a.order - b.order).map(({ title, url }) => ({ title, url }))
-    }));
+    return undefined;
 }

package/dist/fallbacks/changelog.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `svelte-docsmith/changelog` — the generated release index.
+ *
+ * At build time the `docsmith()` Vite plugin (in `vite.config.ts`) intercepts
+ * this import and replaces it with your package's `CHANGELOG.md`, parsed into
+ * releases and dated from git. This file is only the fallback that runs when
+ * the plugin is missing — see {@link missingPluginError}.
+ */
+import type { ChangelogRelease } from '../core/changelog.js';
+export declare const releases: ChangelogRelease[];

package/dist/fallbacks/changelog.js

@@ -0,0 +1,3 @@
+import { missingPluginError } from './missing-plugin.js';
+export const releases = [];
+throw missingPluginError('changelog');

package/dist/generate/feed.d.ts

@@ -0,0 +1,35 @@
+import type { ChangelogRelease } from '../core/changelog.js';
+/** Site details the feed needs beyond the releases themselves. */
+export type FeedSite = {
+    /** Canonical origin, e.g. `https://docs.example.com`. */
+    url: string;
+    /** Feed title, usually the site title. */
+    title: string;
+    /** One-line feed description. */
+    description?: string;
+    /** Path the changelog lives at. Default: `/changelog`. */
+    path?: string;
+};
+/**
+ * Build an Atom feed body from parsed changelog releases. Framework-agnostic:
+ * wire it into a SvelteKit `src/routes/changelog.xml/+server.ts` over the
+ * generated `svelte-docsmith/changelog` index.
+ *
+ * ```ts
+ * import { releases } from 'svelte-docsmith/changelog';
+ * import { generateFeed } from 'svelte-docsmith';
+ *
+ * export const prerender = true;
+ * export function GET() {
+ *   const body = generateFeed(releases, {
+ *     url: 'https://my-docs.dev',
+ *     title: 'My Library'
+ *   });
+ *   return new Response(body, { headers: { 'content-type': 'application/atom+xml' } });
+ * }
+ * ```
+ *
+ * Atom rather than RSS because it requires an unambiguous per-entry id and
+ * update timestamp, which is exactly what a version and its release date give.
+ */
+export declare function generateFeed(releases: ChangelogRelease[], site: FeedSite): string;