svelte-docsmith 0.11.0 → 0.12.0

package/dist/buildtime/archive.js

@@ -7,6 +7,7 @@
  * Kept here rather than in `bin/` so they are typechecked and unit-tested; the
  * CLI is a thin wrapper over them. See `docs/adr/0002-archives-are-rewritten-source-copies.md`.
  */
+import { atBoundary, firstSegmentUnder } from '../utils/url.js';
 import { outsideCodeFences, withFrontmatter } from './markdown-source.js';
 /** Route files at the docs root that an archive nested inside it already inherits. */
 export function isInheritedRouteFile(name) {
@@ -28,10 +29,11 @@ export function rewriteDocsLinks(text, options) {
     const skip = new Set([...(options.archivedIds ?? []), versionId]);
     const pattern = new RegExp(`(\\]\\(|href="|href='|\\]:[ \\t]+)(${escapeRe(docsBase)})([^)"'\\s]*)`, 'g');
     return outsideCodeFences(text, (chunk) => chunk.replace(pattern, (match, prefix, base, rest) => {
-        // Guard the segment boundary: `/docsmith` must not become `/docs/v1mith`.
-        if (rest && !/^[/#?]/.test(rest))
+        // The regex has already matched the base, so guard the boundary on what
+        // follows it: `/docsmith` must not become `/docs/v1mith`.
+        if (!atBoundary(rest))
             return match;
-        const firstSegment = rest.startsWith('/') ? rest.slice(1).split(/[/#?]/)[0] : '';
+        const firstSegment = firstSegmentUnder(rest, '');
         if (firstSegment && skip.has(firstSegment))
             return match;
         return `${prefix}${base}/${versionId}${rest}`;

package/dist/buildtime/paths.d.ts

@@ -1,7 +1,12 @@
+/**
+ * The URL a directory under the routes root is served at: `<routes>/docs/intro`
+ * becomes `/docs/intro`. The routes root itself becomes `/`.
+ */
+export declare function urlFor(routesDir: string, dir: string): string;
 /**
  * The docs URL base, e.g. `/docs`, from the content directory's location under
- * the routes directory. This is the same mapping the collectors use to turn a
- * page's directory into its URL, so a page at `<routes>/docs/intro/+page.md` is
- * served at `/docs/intro` under a base of `/docs`.
+ * the routes directory. The same mapping a page's own directory goes through, so
+ * a page at `<routes>/docs/intro/+page.md` is served at `/docs/intro` under a
+ * base of `/docs`.
  */
 export declare function docsBaseFrom(routesDir: string, contentDir: string): string;

package/dist/buildtime/paths.js

@@ -4,12 +4,20 @@
  * separately is how they drift.
  */
 import path from 'node:path';
+/**
+ * The URL a directory under the routes root is served at: `<routes>/docs/intro`
+ * becomes `/docs/intro`. The routes root itself becomes `/`.
+ */
+export function urlFor(routesDir, dir) {
+    const rel = path.relative(routesDir, dir).split(path.sep).join('/');
+    return '/' + rel;
+}
 /**
  * The docs URL base, e.g. `/docs`, from the content directory's location under
- * the routes directory. This is the same mapping the collectors use to turn a
- * page's directory into its URL, so a page at `<routes>/docs/intro/+page.md` is
- * served at `/docs/intro` under a base of `/docs`.
+ * the routes directory. The same mapping a page's own directory goes through, so
+ * a page at `<routes>/docs/intro/+page.md` is served at `/docs/intro` under a
+ * base of `/docs`.
  */
 export function docsBaseFrom(routesDir, contentDir) {
-    return '/' + path.relative(routesDir, contentDir).split(path.sep).join('/');
+    return urlFor(routesDir, contentDir);
 }

package/dist/buildtime/vite/collect.d.ts

@@ -1,24 +1,33 @@
 import type { DocsContentItem, LlmsDoc, SearchDoc } from '../../core/content.js';
 import type { DocsVersions } from '../../core/version.js';
+import { type SourcePage } from './pages.js';
+/** Where the pages sit, which is what turns a page's file into a URL and a version. */
+export type IndexOptions = {
+    /** The docs root the pages were read from. */
+    contentDir: string;
+    /** Routes root, so `<routes>/docs/intro/+page.md` becomes `/docs/intro`. */
+    routesDir: string;
+    /** Declared versions, when the site has them. */
+    versions?: DocsVersions;
+};
 /**
- * Scan `contentDir` for `+page.md`/`+page.svx` files and read the frontmatter
- * fields the sidebar needs (plus the heading list for a server-rendered TOC and
- * an estimated reading time), deriving each page's URL from its directory
- * relative to `routesDir`. Pure and synchronous so it can be unit-tested.
+ * The sidebar's index: the frontmatter fields navigation needs, plus the heading
+ * list for a server-rendered TOC and an estimated reading time. Served as the
+ * eagerly-imported `svelte-docsmith/content` virtual module.
+ *
+ * `lastUpdated` is read off the page rather than looked up here, so pass pages
+ * that have been through `withCommitDates` or the column comes out blank.
  */
-export declare function collectDocs(contentDir: string, routesDir: string, versions?: DocsVersions): DocsContentItem[];
+export declare function contentIndex(pages: SourcePage[], options: IndexOptions): DocsContentItem[];
 /**
- * Build the search records for every page under `contentDir`: title, section,
- * description, heading list, and plain-text body. Served as the lazy-loaded
- * `svelte-docsmith/search` virtual module so search can index bodies without
- * bloating the eagerly-imported nav index. The missing-directory case is
- * already reported by {@link collectDocs}, so this stays quiet.
+ * The search index: title, section, description, heading list, and plain-text
+ * body. Served as the lazy-loaded `svelte-docsmith/search` virtual module so
+ * search can index bodies without bloating the eagerly-imported content index.
  */
-export declare function collectSearchDocs(contentDir: string, routesDir: string, versions?: DocsVersions): SearchDoc[];
+export declare function searchIndex(pages: SourcePage[], options: IndexOptions): SearchDoc[];
 /**
- * Build the LLM records for every page: title, section, description, and the
- * full markdown content. Served as the `svelte-docsmith/llms` virtual module and
- * consumed server-side by `llms.txt` / `llms-full.txt` routes, so it never ships
- * to the client.
+ * The LLM index: title, section, description, and the full markdown content.
+ * Served as the `svelte-docsmith/llms` virtual module and consumed server-side
+ * by `llms.txt` / `llms-full.txt` routes, so it never ships to the client.
  */
-export declare function collectLlmsDocs(contentDir: string, routesDir: string, versions?: DocsVersions): LlmsDoc[];
+export declare function llmsIndex(pages: SourcePage[], options: IndexOptions): LlmsDoc[];

package/dist/buildtime/vite/collect.js

@@ -1,9 +1,51 @@
-import fs from 'node:fs';
+/**
+ * The three generated indexes, each a projection of the same page list. Nothing
+ * here reads the filesystem or spawns a process: a build hands these functions
+ * pages read by `./pages.js`, and a test hands them literals. Both go down the
+ * same path, so what the sidebar, search and llms.txt show is decided in one
+ * place and can be checked without a docs root on disk.
+ */
 import path from 'node:path';
-import { listPageFiles } from './pages.js';
-import { parseFrontmatter } from './frontmatter.js';
+import { firstSegmentUnder } from '../../utils/url.js';
+import { docsBaseFrom, urlFor } from '../paths.js';
+import { titleOf } from './pages.js';
 import { extractLlmsContent, extractSearchText, extractToc, readingMinutes } from './extract.js';
-import { lastCommitDate } from '../git.js';
+/**
+ * Resolve every titled page against the site's layout. Shared by all three
+ * indexes so they can never disagree about which pages exist or where they live.
+ */
+function indexedPages(pages, options) {
+    const resolved = [];
+    const docsBase = docsBaseFrom(options.routesDir, options.contentDir);
+    for (const page of pages) {
+        const title = titleOf(page);
+        if (title === undefined)
+            continue;
+        const url = urlFor(options.routesDir, path.dirname(page.file));
+        resolved.push({ ...page, url, title, version: versionOf(url) });
+    }
+    // Stable output keeps the generated modules diff-friendly across rebuilds.
+    return resolved.sort((a, b) => a.url.localeCompare(b.url));
+    /**
+     * A page belongs to an archived version when the first segment of its URL below
+     * the docs base is that archive's id; everything else is the current version,
+     * which lives unprefixed at the docs base.
+     *
+     * Decided in URL space, by the same rule `activeVersion` applies to the reader's
+     * pathname at runtime. Deciding it from the directory instead would be a second
+     * rule for the same question, in a second vocabulary, free to drift from the one
+     * the reader is actually served by. No versions ⇒ undefined, which keeps an
+     * unversioned site's index byte-for-byte what it was.
+     */
+    function versionOf(url) {
+        const { versions } = options;
+        if (!versions)
+            return undefined;
+        const segment = firstSegmentUnder(url, docsBase);
+        const archived = versions.archived?.find((v) => v.id === segment);
+        return archived ? archived.id : versions.current.id;
+    }
+}
 /**
  * Read a page's `section` frontmatter: a string is one level, an array is a
  * nested group path. Non-string array members are dropped; anything else is
@@ -33,116 +75,68 @@ function sectionKey(value) {
     return Array.isArray(section) ? section.join(' / ') : section;
 }
 /**
- * Walk every nav-worthy page under `contentDir` once: a page is nav-worthy when
- * its frontmatter has a string `title`. Yields the raw source, parsed
- * frontmatter, derived URL, and title so every index (nav, search, llms) can be
- * built from a single read of each file.
+ * A frontmatter field, when it holds the type the index expects. Frontmatter is
+ * whatever the author typed, so a field of the wrong type is dropped rather than
+ * carried into the index as one.
  */
-function* eachTitledPage(contentDir, routesDir, versions) {
-    for (const file of listPageFiles(contentDir)) {
-        const source = fs.readFileSync(file, 'utf-8');
-        const front = parseFrontmatter(source, file);
-        if (typeof front.title !== 'string')
-            continue;
-        const dir = path.dirname(file);
-        const url = '/' + path.relative(routesDir, dir).split(path.sep).join('/');
-        yield { source, front, url, title: front.title, file, version: versionOf(dir) };
-    }
-    /**
-     * A page belongs to an archived version when its first directory segment under
-     * the content dir is that archive's id; everything else is the current
-     * version, which lives unprefixed at the docs root. No versions ⇒ undefined,
-     * which keeps an unversioned site's index byte-for-byte what it was.
-     */
-    function versionOf(dir) {
-        if (!versions)
-            return undefined;
-        const firstSegment = path.relative(contentDir, dir).split(path.sep)[0];
-        const archived = versions.archived?.find((v) => v.id === firstSegment);
-        return archived ? archived.id : versions.current.id;
-    }
+function stringField(front, key) {
+    return typeof front[key] === 'string' ? front[key] : undefined;
+}
+/** As {@link stringField}, for the numeric fields. */
+function numberField(front, key) {
+    return typeof front[key] === 'number' ? front[key] : undefined;
 }
 /**
- * Scan `contentDir` for `+page.md`/`+page.svx` files and read the frontmatter
- * fields the sidebar needs (plus the heading list for a server-rendered TOC and
- * an estimated reading time), deriving each page's URL from its directory
- * relative to `routesDir`. Pure and synchronous so it can be unit-tested.
+ * The sidebar's index: the frontmatter fields navigation needs, plus the heading
+ * list for a server-rendered TOC and an estimated reading time. Served as the
+ * eagerly-imported `svelte-docsmith/content` virtual module.
+ *
+ * `lastUpdated` is read off the page rather than looked up here, so pass pages
+ * that have been through `withCommitDates` or the column comes out blank.
  */
-export function collectDocs(contentDir, routesDir, versions) {
-    if (!fs.existsSync(contentDir)) {
-        console.warn(`[svelte-docsmith] content directory not found: ${contentDir}\n` +
-            `  The sidebar will be empty. Create your doc pages there, or point docsmith() at the right place with \`content\`.`);
-        return [];
-    }
-    const items = [];
-    for (const { source, front, url, title, file, version } of eachTitledPage(contentDir, routesDir, versions)) {
-        items.push({
-            title,
-            path: url,
-            description: typeof front.description === 'string' ? front.description : undefined,
-            section: readSection(front.section),
-            order: typeof front.order === 'number' ? front.order : undefined,
-            sourcePath: path.relative(process.cwd(), file).split(path.sep).join('/'),
-            // Frontmatter wins over git so an archived page keeps the date it last
-            // really changed: archiving copies every page in one commit, which would
-            // otherwise stamp the whole archive with the day it was created.
-            lastUpdated: typeof front.lastUpdated === 'string' ? front.lastUpdated : lastCommitDate(file),
-            readingTime: readingMinutes(extractSearchText(source)),
-            toc: extractToc(source),
-            version
-        });
-    }
-    if (items.length === 0) {
-        console.warn(`[svelte-docsmith] no doc pages found under ${contentDir}\n` +
-            `  Add \`+page.md\` files with at least a \`title:\` in their frontmatter to populate the sidebar.`);
-    }
-    // Stable output keeps the generated module diff-friendly across rebuilds.
-    return items.sort((a, b) => a.path.localeCompare(b.path));
+export function contentIndex(pages, options) {
+    return indexedPages(pages, options).map((page) => ({
+        title: page.title,
+        path: page.url,
+        description: stringField(page.frontmatter, 'description'),
+        section: readSection(page.frontmatter.section),
+        order: numberField(page.frontmatter, 'order'),
+        sourcePath: path.relative(process.cwd(), page.file).split(path.sep).join('/'),
+        lastUpdated: page.lastUpdated,
+        readingTime: readingMinutes(extractSearchText(page.source)),
+        toc: extractToc(page.source),
+        version: page.version
+    }));
 }
 /**
- * Build the search records for every page under `contentDir`: title, section,
- * description, heading list, and plain-text body. Served as the lazy-loaded
- * `svelte-docsmith/search` virtual module so search can index bodies without
- * bloating the eagerly-imported nav index. The missing-directory case is
- * already reported by {@link collectDocs}, so this stays quiet.
+ * The search index: title, section, description, heading list, and plain-text
+ * body. Served as the lazy-loaded `svelte-docsmith/search` virtual module so
+ * search can index bodies without bloating the eagerly-imported content index.
  */
-export function collectSearchDocs(contentDir, routesDir, versions) {
-    if (!fs.existsSync(contentDir))
-        return [];
-    const docs = [];
-    for (const { source, front, url, title, version } of eachTitledPage(contentDir, routesDir, versions)) {
-        docs.push({
-            path: url,
-            title,
-            section: sectionLabel(front.section),
-            description: typeof front.description === 'string' ? front.description : undefined,
-            headings: extractToc(source).map((entry) => entry.title),
-            text: extractSearchText(source),
-            version
-        });
-    }
-    return docs.sort((a, b) => a.path.localeCompare(b.path));
+export function searchIndex(pages, options) {
+    return indexedPages(pages, options).map((page) => ({
+        path: page.url,
+        title: page.title,
+        section: sectionLabel(page.frontmatter.section),
+        description: stringField(page.frontmatter, 'description'),
+        headings: extractToc(page.source).map((entry) => entry.title),
+        text: extractSearchText(page.source),
+        version: page.version
+    }));
 }
 /**
- * Build the LLM records for every page: title, section, description, and the
- * full markdown content. Served as the `svelte-docsmith/llms` virtual module and
- * consumed server-side by `llms.txt` / `llms-full.txt` routes, so it never ships
- * to the client.
+ * The LLM index: title, section, description, and the full markdown content.
+ * Served as the `svelte-docsmith/llms` virtual module and consumed server-side
+ * by `llms.txt` / `llms-full.txt` routes, so it never ships to the client.
  */
-export function collectLlmsDocs(contentDir, routesDir, versions) {
-    if (!fs.existsSync(contentDir))
-        return [];
-    const docs = [];
-    for (const { source, front, url, title, version } of eachTitledPage(contentDir, routesDir, versions)) {
-        docs.push({
-            path: url,
-            title,
-            section: sectionKey(front.section),
-            order: typeof front.order === 'number' ? front.order : undefined,
-            description: typeof front.description === 'string' ? front.description : undefined,
-            content: extractLlmsContent(source, title),
-            version
-        });
-    }
-    return docs.sort((a, b) => a.path.localeCompare(b.path));
+export function llmsIndex(pages, options) {
+    return indexedPages(pages, options).map((page) => ({
+        path: page.url,
+        title: page.title,
+        section: sectionKey(page.frontmatter.section),
+        order: numberField(page.frontmatter, 'order'),
+        description: stringField(page.frontmatter, 'description'),
+        content: extractLlmsContent(page.source, page.title),
+        version: page.version
+    }));
 }

package/dist/buildtime/vite/extract.d.ts

@@ -3,8 +3,6 @@ export type TocEntry = {
     title: string;
     depth: 2 | 3;
 };
-/** Strip inline markdown so a heading's TOC label is plain text. */
-export declare function stripInlineMarkdown(text: string): string;
 /**
  * Reduce a markdown page to plain, searchable body text: prose and heading text
  * with frontmatter, `<script>`/`<style>` blocks, fenced code, HTML/Svelte tags,

package/dist/buildtime/vite/extract.js

@@ -5,7 +5,7 @@ function withoutSetupBlocks(body) {
     return body.replace(/<script[\s\S]*?<\/script>/gi, '').replace(/<style[\s\S]*?<\/style>/gi, '');
 }
 /** Strip inline markdown so a heading's TOC label is plain text. */
-export function stripInlineMarkdown(text) {
+function stripInlineMarkdown(text) {
     return text
         .replace(/!\[([^\]]*)\]\([^)]*\)/g, '$1')
         .replace(/`([^`]+)`/g, '$1')

package/dist/buildtime/vite/index.d.ts

@@ -1,7 +1,5 @@
 import type { Plugin } from 'vite';
 import { type DocsVersions } from '../../core/version.js';
-export { collectDocs, collectLlmsDocs, collectSearchDocs } from './collect.js';
-export { collectReleases } from './releases.js';
 export interface DocsmithViteOptions {
     /** Directory scanned for doc pages. Default: `'src/routes/docs'`. */
     content?: string;

package/dist/buildtime/vite/index.js

@@ -13,8 +13,9 @@
  *  3. The **`?source` transform** powering `LiveExample`: importing
  *     `Component.svelte?source` yields that file's Shiki-highlighted source.
  *
- * The per-index scanning lives in `./collect.js`; this file owns the two Vite
- * plugins and re-exports the collectors for consumers and tests.
+ * Reading the docs root lives in `./pages.js` and building each index from what
+ * it read lives in `./collect.js`; this file owns the two Vite plugins, and is
+ * the only layer that reports to the console.
  */
 import fs from 'node:fs';
 import path from 'node:path';
@@ -22,11 +23,9 @@ import { DEFAULT_THEMES, lazyHighlighter } from '../highlight.js';
 import { checkVersions, resolveVersions } from '../../core/version.js';
 import { ARCHIVE_MARKER, discoverArchives } from '../archives.js';
 import { docsBaseFrom } from '../paths.js';
-import { isPageFile, listPageFiles } from './pages.js';
-import { collectDocs, collectLlmsDocs, collectSearchDocs } from './collect.js';
+import { isPageFile, readSourcePages, withCommitDates } from './pages.js';
+import { contentIndex, llmsIndex, searchIndex } from './collect.js';
 import { collectReleases } from './releases.js';
-export { collectDocs, collectLlmsDocs, collectSearchDocs } from './collect.js';
-export { collectReleases } from './releases.js';
 /**
  * The svelte-docsmith Vite plugin. Add it to `plugins` in `vite.config.ts`:
  *
@@ -47,6 +46,21 @@ const LLMS_SPECIFIER = 'svelte-docsmith/llms';
 const VIRTUAL_LLMS_ID = '\0svelte-docsmith:llms';
 const CHANGELOG_SPECIFIER = 'svelte-docsmith/changelog';
 const VIRTUAL_CHANGELOG_ID = '\0svelte-docsmith:changelog';
+/**
+ * Tell the author when their docs root produced nothing, and why. An empty
+ * sidebar is otherwise silent: the build succeeds and the site renders, so
+ * without this the first sign of a misconfigured `content` is a missing nav.
+ */
+function warnAboutDocsRoot(contentDir, exists, indexed) {
+    if (!exists) {
+        console.warn(`[svelte-docsmith] content directory not found: ${contentDir}\n` +
+            `  The sidebar will be empty. Create your doc pages there, or point docsmith() at the right place with \`content\`.`);
+    }
+    else if (indexed === 0) {
+        console.warn(`[svelte-docsmith] no doc pages found under ${contentDir}\n` +
+            `  Add \`+page.md\` files with at least a \`title:\` in their frontmatter to populate the sidebar.`);
+    }
+}
 function contentIndexPlugin(options) {
     const contentDir = path.resolve(options.content ?? 'src/routes/docs');
     const routesDir = path.resolve(options.routes ?? 'src/routes');
@@ -54,7 +68,8 @@ function contentIndexPlugin(options) {
     const docsBase = docsBaseFrom(routesDir, contentDir);
     const changelogFile = options.changelog === false ? undefined : path.resolve(options.changelog ?? 'CHANGELOG.md');
     const changelogRoute = options.changelogPath ?? '/changelog';
-    const changelogOverrides = path.join(routesDir, changelogRoute.replace(/^\//, ''));
+    const changelogOverrides = path.join(routesDir, changelogRoute);
+    const indexOptions = { contentDir, routesDir, versions };
     return {
         name: 'docsmith-content',
         enforce: 'pre',
@@ -73,30 +88,34 @@ function contentIndexPlugin(options) {
             // body re-runs this load. A directory here is treated as an
             // unresolvable import by vite:import-analysis; new/removed pages are
             // handled by the watcher in configureServer.
+            const watch = (pages) => {
+                for (const page of pages)
+                    this.addWatchFile(page.file);
+            };
             if (id === VIRTUAL_CONTENT_ID) {
-                for (const file of listPageFiles(contentDir))
-                    this.addWatchFile(file);
-                // Before anything is collected: a config that disagrees with the docs
-                // root produces an index that is wrong rather than empty, so it has to
-                // fail here rather than render. Re-runs on invalidation, so archiving
-                // during `dev` reports immediately.
+                // Before anything is read: a config that disagrees with the docs root
+                // produces an index that is wrong rather than empty, so it has to fail
+                // here rather than render. Re-runs on invalidation, so archiving during
+                // `dev` reports immediately.
                 checkVersions(versions, discoverArchives(contentDir), ARCHIVE_MARKER);
-                const docs = collectDocs(contentDir, routesDir, versions);
+                const { pages, exists } = readSourcePages(contentDir);
+                watch(pages);
+                // Only this index has a date field, so only this one pays for git.
+                const docs = contentIndex(withCommitDates(pages), indexOptions);
+                warnAboutDocsRoot(contentDir, exists, docs.length);
                 const resolved = resolveVersions(versions, docsBase, docs);
                 return (`export const docs = ${JSON.stringify(docs, null, 2)};\n` +
                     `export const versions = ${JSON.stringify(resolved, null, 2)};\n`);
             }
             if (id === VIRTUAL_SEARCH_ID) {
-                for (const file of listPageFiles(contentDir))
-                    this.addWatchFile(file);
-                const docs = collectSearchDocs(contentDir, routesDir, versions);
-                return `export const docs = ${JSON.stringify(docs)};\n`;
+                const { pages } = readSourcePages(contentDir);
+                watch(pages);
+                return `export const docs = ${JSON.stringify(searchIndex(pages, indexOptions))};\n`;
             }
             if (id === VIRTUAL_LLMS_ID) {
-                for (const file of listPageFiles(contentDir))
-                    this.addWatchFile(file);
-                const docs = collectLlmsDocs(contentDir, routesDir, versions);
-                return `export const docs = ${JSON.stringify(docs)};\n`;
+                const { pages } = readSourcePages(contentDir);
+                watch(pages);
+                return `export const docs = ${JSON.stringify(llmsIndex(pages, indexOptions))};\n`;
             }
             if (id === VIRTUAL_CHANGELOG_ID) {
                 if (!changelogFile)

package/dist/buildtime/vite/pages.d.ts

@@ -1,5 +1,56 @@
+/**
+ * One doc page as authored on disk, before any index-specific derivation. Its
+ * URL, version, headings and search text are all derived from these fields, so
+ * everything downstream of the read is pure.
+ */
+export type SourcePage = {
+    /** Absolute path to the page file. */
+    file: string;
+    /** The page's raw markdown, frontmatter included. */
+    source: string;
+    /** The page's parsed frontmatter, `{}` when it has none. */
+    frontmatter: Record<string, unknown>;
+    /**
+     * The day (`YYYY-MM-DD`) the page last changed. Only {@link withCommitDates}
+     * fills this in, so it is absent on a page list that never went through it.
+     */
+    lastUpdated?: string;
+};
 /** Whether a filename is a doc page the plugin should index. */
 export declare function isPageFile(file: string): boolean;
+/**
+ * Turn a page's path and raw markdown into a {@link SourcePage}. Pure, and
+ * shared with tests so an in-memory page is built exactly the way a read one is.
+ */
+export declare function toPage(file: string, source: string): SourcePage;
+/**
+ * Read every doc page under `contentDir`. `exists` distinguishes a missing docs
+ * root from an empty one, which the page list alone cannot: both give no pages,
+ * but only one of them is a misconfiguration worth reporting.
+ */
+export declare function readSourcePages(contentDir: string): {
+    pages: SourcePage[];
+    exists: boolean;
+};
+/**
+ * A page's title, when it has one. A page whose frontmatter has no string
+ * `title` is a stub: no index carries it, so nothing is derived for it and
+ * nothing is looked up about it.
+ */
+export declare function titleOf(page: SourcePage): string | undefined;
+/**
+ * Date each page from the commit that last touched it, skipping the lookup for
+ * pages that carry their own `lastUpdated`. Archiving copies every page in one
+ * commit, so an archive's pages are written with the date they last really
+ * changed and must keep it.
+ *
+ * Deliberately a second pass rather than part of {@link readSourcePages}: it
+ * spawns a git process per page, and only the content index has a date field.
+ * Folding it into the read would make the search and llms indexes pay for a
+ * value neither of them has anywhere to put. For the same reason it skips
+ * untitled pages, which no index carries.
+ */
+export declare function withCommitDates(pages: SourcePage[]): SourcePage[];
 /**
  * List the absolute paths of every `+page.md`/`+page.svx` under `contentDir`.
  */

package/dist/buildtime/vite/pages.js

@@ -1,10 +1,68 @@
+/**
+ * The docs root, and what a page is before any index has looked at it. Reading
+ * stops at a {@link SourcePage} list, which is the only value the index builders
+ * in `./collect.js` see — so the same builders run against a real docs root in
+ * the plugin and against an array of literals in tests.
+ */
 import fs from 'node:fs';
 import path from 'node:path';
+import { parseFrontmatter } from './frontmatter.js';
+import { lastCommitDate } from '../git.js';
 const PAGE_NAMES = ['+page.md', '+page.svx'];
 /** Whether a filename is a doc page the plugin should index. */
 export function isPageFile(file) {
     return PAGE_NAMES.some((name) => file.endsWith(name));
 }
+/**
+ * Turn a page's path and raw markdown into a {@link SourcePage}. Pure, and
+ * shared with tests so an in-memory page is built exactly the way a read one is.
+ */
+export function toPage(file, source) {
+    return { file, source, frontmatter: parseFrontmatter(source, file) };
+}
+/**
+ * Read every doc page under `contentDir`. `exists` distinguishes a missing docs
+ * root from an empty one, which the page list alone cannot: both give no pages,
+ * but only one of them is a misconfiguration worth reporting.
+ */
+export function readSourcePages(contentDir) {
+    if (!fs.existsSync(contentDir))
+        return { pages: [], exists: false };
+    const pages = listPageFiles(contentDir).map((file) => toPage(file, fs.readFileSync(file, 'utf-8')));
+    return { pages, exists: true };
+}
+/**
+ * A page's title, when it has one. A page whose frontmatter has no string
+ * `title` is a stub: no index carries it, so nothing is derived for it and
+ * nothing is looked up about it.
+ */
+export function titleOf(page) {
+    return typeof page.frontmatter.title === 'string' ? page.frontmatter.title : undefined;
+}
+/**
+ * Date each page from the commit that last touched it, skipping the lookup for
+ * pages that carry their own `lastUpdated`. Archiving copies every page in one
+ * commit, so an archive's pages are written with the date they last really
+ * changed and must keep it.
+ *
+ * Deliberately a second pass rather than part of {@link readSourcePages}: it
+ * spawns a git process per page, and only the content index has a date field.
+ * Folding it into the read would make the search and llms indexes pay for a
+ * value neither of them has anywhere to put. For the same reason it skips
+ * untitled pages, which no index carries.
+ */
+export function withCommitDates(pages) {
+    return pages.map((page) => {
+        if (titleOf(page) === undefined)
+            return page;
+        return {
+            ...page,
+            lastUpdated: typeof page.frontmatter.lastUpdated === 'string'
+                ? page.frontmatter.lastUpdated
+                : lastCommitDate(page.file)
+        };
+    });
+}
 /**
  * List the absolute paths of every `+page.md`/`+page.svx` under `contentDir`.
  */

package/dist/buildtime/vite/releases.d.ts

@@ -8,5 +8,3 @@ import type { ChangelogRelease } from '../../core/changelog.js';
  * have one while the rest stay generated.
  */
 export declare function collectReleases(changelogFile: string, overridesDir?: string, routePath?: string): ChangelogRelease[];
-/** Default location of a monorepo package's changelog, relative to the app. */
-export declare function defaultChangelogPath(cwd?: string): string;

package/dist/buildtime/vite/releases.js

@@ -1,5 +1,4 @@
 import fs from 'node:fs';
-import path from 'node:path';
 import { marked } from 'marked';
 import { parseChangelog } from '../changelog.js';
 import { changelogDates } from '../git.js';
@@ -51,7 +50,3 @@ export function collectReleases(changelogFile, overridesDir, routePath = '/chang
         };
     });
 }
-/** Default location of a monorepo package's changelog, relative to the app. */
-export function defaultChangelogPath(cwd = process.cwd()) {
-    return path.resolve(cwd, 'CHANGELOG.md');
-}

package/dist/components/layouts/copy-page-menu.svelte

@@ -7,6 +7,7 @@
 	import Copy from '@lucide/svelte/icons/copy';
 	import FileText from '@lucide/svelte/icons/file-text';
 	import ArrowUpRight from '@lucide/svelte/icons/arrow-up-right';
+	import { join } from '../../utils/url.js';
 
 	const {
 		path,
@@ -21,8 +22,9 @@
 	// Convention: each page's markdown lives at `<path>.md`, served by the
 	// consumer's catch-all endpoint over the `svelte-docsmith/llms` index.
 	const mdHref = $derived(`${path}.md`);
-	const base = $derived((origin || (browser ? location.origin : '')).replace(/\/$/, ''));
-	const absoluteMd = $derived(`${base}${mdHref}`);
+	// Before hydration with no configured origin there is nothing to prefix, and
+	// `join` leaves the link site-relative rather than mangling it.
+	const absoluteMd = $derived(join(origin || (browser ? location.origin : ''), mdHref));
 	const prompt = $derived(`Read ${absoluteMd} so I can ask questions about this page.`);
 	const chatgptHref = $derived(`https://chatgpt.com/?hints=search&q=${encodeURIComponent(prompt)}`);
 	const claudeHref = $derived(`https://claude.ai/new?q=${encodeURIComponent(prompt)}`);

package/dist/components/layouts/docs-header.svelte

@@ -11,7 +11,7 @@
 	import BookOpenText from '@lucide/svelte/icons/book-open-text';
 	import type { Snippet } from 'svelte';
 	import { cn } from '../../utils/cn.js';
-	import { normalizePath } from '../../utils/normalize-path.js';
+	import { firstSegmentUnder, join, normalizePath, under } from '../../utils/url.js';
 	import { useDocsPage } from '../docs-page-context.js';
 
 	const {
@@ -42,11 +42,15 @@
 	 */
 	function isActive(link: DocsmithLink): boolean {
 		if (link.external) return false;
-		const href = normalizePath(link.href);
+		// `href` is only required to be a string, so anchor it at the site root:
+		// `docs/intro` has to light the same section as `/docs/intro`.
+		const href = normalizePath(join('/', link.href));
 		if (href === current) return true;
-		if (href === '/') return false;
-		const section = '/' + href.split('/').filter(Boolean)[0];
-		return current === section || current.startsWith(section + '/');
+		// No first segment means the link is the root, or is not a site path at
+		// all (an absolute URL left unflagged), and owns no section either way.
+		const segment = firstSegmentUnder(href, '/');
+		if (!segment) return false;
+		return under(current, '/' + segment);
 	}
 
 	let isScrolled = $state(false);

package/dist/components/layouts/docs-sidebar.svelte

@@ -2,7 +2,7 @@
 	import { page } from '$app/state';
 	import ChevronRight from '@lucide/svelte/icons/chevron-right';
 	import { cn } from '../../utils/cn.js';
-	import { normalizePath } from '../../utils/normalize-path.js';
+	import { normalizePath } from '../../utils/url.js';
 	import { isNavGroup, type NavGroup, type NavNode } from '../../core/index.js';
 
 	const { nav, class: className = '' }: { nav: NavGroup[]; class?: string } = $props();

package/dist/components/layouts/seo-head.svelte

@@ -1,6 +1,6 @@
 <script lang="ts">
 	import { page } from '$app/state';
-	import { normalizePath } from '../../utils/normalize-path.js';
+	import { join, normalizePath } from '../../utils/url.js';
 	import type { DocsmithConfig } from '../../core/index.js';
 
 	const {
@@ -25,14 +25,16 @@
 	const ogTitle = $derived(title ?? config.title);
 	const metaDescription = $derived(description ?? config.description);
 
-	const origin = $derived(config.url?.replace(/\/$/, ''));
-	// Absolute URLs need a configured origin; otherwise canonical/og:url are omitted.
-	const canonical = $derived(origin ? origin + normalizePath(page.url.pathname) : undefined);
+	// Absolute URLs need a configured origin; otherwise canonical/og:url are
+	// omitted rather than emitted relative, which `join` alone would do.
+	const canonical = $derived(
+		config.url ? join(config.url, normalizePath(page.url.pathname)) : undefined
+	);
 	const image = $derived.by(() => {
 		const src = config.ogImage;
 		if (!src) return undefined;
 		if (/^https?:\/\//.test(src)) return src;
-		return origin ? origin + '/' + src.replace(/^\//, '') : src;
+		return config.url ? join(config.url, src) : src;
 	});
 </script>
 

package/dist/core/changelog.d.ts

@@ -29,6 +29,9 @@ export type ChangelogRelease = {
      * 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.
+     *
+     * Joined to the origin for the feed with exactly one slash between, so the
+     * leading slash is optional.
      */
     path?: string;
 };

package/dist/core/docs-page.js

@@ -1,6 +1,6 @@
 import { navFromContent, flattenNav, navTrail } from './nav.js';
 import { activeVersion, currentVersion, mapPathToVersion, scopeContent } from './version.js';
-import { normalizePath } from '../utils/normalize-path.js';
+import { join, normalizePath } from '../utils/url.js';
 /**
  * Resolve the page being read. `pathname` is taken raw (normalized here, so the
  * caller has one fewer place to remember) and every field is derived from the
@@ -34,9 +34,7 @@ export function resolveDocsPage(input) {
         scopedContent,
         nav,
         entry,
-        editHref: editUrl && entry?.sourcePath && !isArchived
-            ? editUrl.replace(/\/$/, '') + '/' + entry.sourcePath
-            : undefined,
+        editHref: editUrl && entry?.sourcePath && !isArchived ? join(editUrl, entry.sourcePath) : undefined,
         lastUpdated: parseDate(entry?.lastUpdated),
         readingMinutes: entry?.readingTime,
         prev: pageIndex > 0 ? flatNav[pageIndex - 1] : undefined,

package/dist/core/version.js

@@ -1,9 +1,5 @@
 import { navFromContent, flattenNav } from './nav.js';
-import { normalizePath } from '../utils/normalize-path.js';
-/** True when `pathname` is `base` or sits beneath it on a segment boundary. */
-function underBase(pathname, base) {
-    return pathname === base || pathname.startsWith(base + '/');
-}
+import { join, normalizePath, under } from '../utils/url.js';
 /**
  * Legal version id. Must start alphanumeric: an archived id is both a directory
  * name and a URL segment, so `.`, `..` and dotfiles would escape the docs root
@@ -130,7 +126,7 @@ export function resolveVersions(versions, docsBase, content) {
     };
     return [
         resolve(versions.current, base, true),
-        ...(versions.archived ?? []).map((version) => resolve(version, normalizePath(base + '/' + version.id), false))
+        ...(versions.archived ?? []).map((version) => resolve(version, join(base, version.id), false))
     ];
 }
 /**
@@ -143,7 +139,7 @@ export function activeVersion(versions, pathname) {
     const path = normalizePath(pathname);
     let best;
     for (const v of versions) {
-        if (underBase(path, v.basePath) && (!best || v.basePath.length > best.basePath.length)) {
+        if (under(path, v.basePath) && (!best || v.basePath.length > best.basePath.length)) {
             best = v;
         }
     }
@@ -179,8 +175,8 @@ export function scopeContent(content, versionId) {
  */
 export function mapPathToVersion(pathname, from, to, targetPaths) {
     const path = normalizePath(pathname);
-    const rel = underBase(path, from.basePath) ? path.slice(from.basePath.length) : '';
-    const candidate = normalizePath(to.basePath + rel);
+    const rel = under(path, from.basePath) ? path.slice(from.basePath.length) : '';
+    const candidate = join(to.basePath, rel);
     const set = targetPaths instanceof Set ? targetPaths : new Set(targetPaths);
     return set.has(candidate) ? candidate : to.landing;
 }

package/dist/generate/feed.d.ts

@@ -7,7 +7,10 @@ export type FeedSite = {
     title: string;
     /** One-line feed description. */
     description?: string;
-    /** Path the changelog lives at. Default: `/changelog`. */
+    /**
+     * Path the changelog lives at. Default: `/changelog`. Joined to the origin with
+     * exactly one slash between, so the leading slash is optional.
+     */
     path?: string;
 };
 /**

package/dist/generate/feed.js

@@ -1,17 +1,5 @@
-const escapeXml = (s) => s.replace(/[&<>'"]/g, (c) => {
-    switch (c) {
-        case '&':
-            return '&amp;';
-        case '<':
-            return '&lt;';
-        case '>':
-            return '&gt;';
-        case "'":
-            return '&apos;';
-        default:
-            return '&quot;';
-    }
-});
+import { join } from '../utils/url.js';
+import { escapeXml } from './xml.js';
 /** A release's entries flattened to plain text, grouped by kind. */
 function summarise(release) {
     return release.groups
@@ -41,17 +29,17 @@ function summarise(release) {
  * update timestamp, which is exactly what a version and its release date give.
  */
 export function generateFeed(releases, site) {
-    const origin = site.url.replace(/\/$/, '');
     const path = site.path ?? '/changelog';
-    const feedUrl = `${origin}${path}.xml`;
+    const changelogUrl = join(site.url, path);
+    const feedUrl = `${changelogUrl}.xml`;
     // A feed needs an updated timestamp; fall back to now when no release
     // carries a date, so the document stays valid.
     const updated = releases.find((r) => r.date)?.date ?? new Date().toISOString();
     const entries = releases
         .map((release) => {
         const link = release.path
-            ? `${origin}${release.path}`
-            : `${origin}${path}#${release.version}`;
+            ? join(site.url, release.path)
+            : `${changelogUrl}#${release.version}`;
         return [
             '\t<entry>',
             `\t\t<title>${escapeXml(release.version)}</title>`,
@@ -69,7 +57,7 @@ export function generateFeed(releases, site) {
         `\t<title>${escapeXml(site.title)}</title>`,
         site.description ? `\t<subtitle>${escapeXml(site.description)}</subtitle>` : '',
         `\t<id>${escapeXml(feedUrl)}</id>`,
-        `\t<link href="${escapeXml(origin + path)}" />`,
+        `\t<link href="${escapeXml(changelogUrl)}" />`,
         `\t<link rel="self" href="${escapeXml(feedUrl)}" />`,
         `\t<updated>${escapeXml(updated)}</updated>`,
         entries,

package/dist/generate/llms.d.ts

@@ -3,7 +3,10 @@ import type { LlmsDoc } from '../core/content.js';
 export type LlmsSite = {
     title: string;
     description?: string;
-    /** Absolute origin, e.g. `https://my-docs.dev`, used to make links absolute. */
+    /**
+     * Absolute origin, e.g. `https://my-docs.dev`, used to make links absolute.
+     * Without it the links stay site-relative.
+     */
     origin?: string;
 };
 /**

package/dist/generate/llms.js

@@ -1,3 +1,4 @@
+import { join } from '../utils/url.js';
 /**
  * Group docs by section and put both the sections and the docs within them in
  * sidebar reading order: items by their `order`, sections by the smallest
@@ -38,7 +39,7 @@ function bySection(docs) {
  * ```
  */
 export function generateLlmsTxt(site, docs) {
-    const base = (site.origin ?? '').replace(/\/$/, '');
+    const origin = site.origin ?? '';
     const out = [`# ${site.title}`];
     if (site.description)
         out.push('', `> ${site.description}`);
@@ -46,7 +47,7 @@ export function generateLlmsTxt(site, docs) {
         out.push('', `## ${section}`, '');
         for (const doc of items) {
             const suffix = doc.description ? `: ${doc.description}` : '';
-            out.push(`- [${doc.title}](${base}${doc.path})${suffix}`);
+            out.push(`- [${doc.title}](${join(origin, doc.path)})${suffix}`);
         }
     }
     return out.join('\n') + '\n';

package/dist/generate/sitemap.d.ts

@@ -1,6 +1,9 @@
 /** One entry in a sitemap: a page path (joined to the origin) and optional last-modified date. */
 export type SitemapEntry = {
-    /** Absolute path, e.g. `/docs/intro`. Joined to the origin. */
+    /**
+     * Page path, e.g. `/docs/intro`. Joined to the origin with exactly one slash
+     * between, so the leading slash is optional.
+     */
     path: string;
     /** Last-modified date; an ISO string or `YYYY-MM-DD`. Only the date is emitted. */
     lastmod?: string;

package/dist/generate/sitemap.js

@@ -1,17 +1,5 @@
-const escapeXml = (s) => s.replace(/[&<>'"]/g, (c) => {
-    switch (c) {
-        case '&':
-            return '&amp;';
-        case '<':
-            return '&lt;';
-        case '>':
-            return '&gt;';
-        case "'":
-            return '&apos;';
-        default:
-            return '&quot;';
-    }
-});
+import { join } from '../utils/url.js';
+import { escapeXml } from './xml.js';
 /**
  * Build a sitemap.xml body from a list of pages. Framework-agnostic: wire it
  * into a SvelteKit `src/routes/sitemap.xml/+server.ts` that maps the generated
@@ -32,10 +20,9 @@ const escapeXml = (s) => s.replace(/[&<>'"]/g, (c) => {
  * ```
  */
 export function generateSitemap(origin, entries) {
-    const base = origin.replace(/\/$/, '');
     const urls = entries
         .map(({ path, lastmod }) => {
-        const loc = `\t\t<loc>${escapeXml(base + path)}</loc>`;
+        const loc = `\t\t<loc>${escapeXml(join(origin, path))}</loc>`;
         const mod = lastmod ? `\n\t\t<lastmod>${lastmod.slice(0, 10)}</lastmod>` : '';
         return `\t<url>\n${loc}${mod}\n\t</url>`;
     })

package/dist/generate/xml.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Shared escaping for the XML documents this layer emits. `sitemap.xml` and the
+ * changelog's Atom feed both interpolate site-supplied strings into markup, and
+ * both need the same five characters escaped, so the rule lives here rather than
+ * once per generator.
+ */
+/**
+ * Escape a string for use as XML text or as an attribute value. All five
+ * predefined entities are escaped, rather than the subset each position strictly
+ * needs, so a caller can never pick the wrong one.
+ */
+export declare function escapeXml(s: string): string;

package/dist/generate/xml.js

@@ -0,0 +1,27 @@
+/**
+ * Shared escaping for the XML documents this layer emits. `sitemap.xml` and the
+ * changelog's Atom feed both interpolate site-supplied strings into markup, and
+ * both need the same five characters escaped, so the rule lives here rather than
+ * once per generator.
+ */
+/**
+ * Escape a string for use as XML text or as an attribute value. All five
+ * predefined entities are escaped, rather than the subset each position strictly
+ * needs, so a caller can never pick the wrong one.
+ */
+export function escapeXml(s) {
+    return s.replace(/[&<>'"]/g, (c) => {
+        switch (c) {
+            case '&':
+                return '&amp;';
+            case '<':
+                return '&lt;';
+            case '>':
+                return '&gt;';
+            case "'":
+                return '&apos;';
+            default:
+                return '&quot;';
+        }
+    });
+}

package/dist/utils/url.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The vocabulary for doc URLs: normalize one for matching, join two to build
+ * one, and ask whether one sits under a base. Every layer that touches URL
+ * space goes through here, because the alternative is what this replaced: the
+ * same trailing-slash strip written with three different regexes and the same
+ * segment-boundary rule written three times, quietly disagreeing.
+ *
+ * Pure string work over a URL's path space. Nothing here knows about docs,
+ * versions or pages; the domain meaning lives in `core/`, which calls in.
+ */
+/**
+ * Strip a trailing slash so route matching is consistent regardless of the
+ * consumer's SvelteKit `trailingSlash` setting: `/docs/intro/` and `/docs/intro`
+ * resolve to the same content entry. The root stays `/`.
+ */
+export declare function normalizePath(pathname: string): string;
+/**
+ * True when nothing follows a base, or what follows starts a new segment rather
+ * than continuing the last one. `?` and `#` count, so the rule holds for a link
+ * href as well as a pathname; that is what stops `/docs` from matching
+ * `/docsmith`.
+ *
+ * Exported for the one caller that has already sliced the base off itself: the
+ * archive link rewriter matches its base with a regex and needs the remainder
+ * afterwards, so it checks the boundary rather than re-testing the whole URL.
+ */
+export declare function atBoundary(rest: string): boolean;
+/** True when `url` is `base` or sits beneath it on a segment boundary. */
+export declare function under(url: string, base: string): boolean;
+/**
+ * The one segment directly below `base`, which is what decides who owns a URL:
+ * an archived version owns `<docs base>/<id>/…`, and a header link owns its
+ * whole first-segment section. `undefined` when `url` is not under `base` at
+ * all, or when the base is the end of it, so callers must handle "no segment"
+ * rather than interpolate it into a path.
+ */
+export declare function firstSegmentUnder(url: string, base: string): string | undefined;
+/**
+ * Join two URL pieces with exactly one slash between them, whichever of them
+ * already carries it. Use it for every URL built from a configured origin or
+ * base, so a trailing slash in someone's config can never double up.
+ *
+ * Only the seam between the two is touched, never the rest of either: rescanning
+ * would turn `https://x.dev` into `https:/x.dev`. Nor is the result normalized,
+ * so `join(origin, '/')` still ends in a slash and a sitemap can carry the home
+ * page.
+ *
+ * An empty `left` returns `right` untouched, which is what an unconfigured
+ * origin needs: `llms.txt` and the copy-page menu fall back to site-relative
+ * links rather than emitting a stray leading slash. Callers that must not degrade
+ * to a relative URL, like `<link rel="canonical">`, have to check the origin
+ * themselves.
+ */
+export declare function join(left: string, right: string): string;

package/dist/utils/url.js

@@ -0,0 +1,84 @@
+/**
+ * The vocabulary for doc URLs: normalize one for matching, join two to build
+ * one, and ask whether one sits under a base. Every layer that touches URL
+ * space goes through here, because the alternative is what this replaced: the
+ * same trailing-slash strip written with three different regexes and the same
+ * segment-boundary rule written three times, quietly disagreeing.
+ *
+ * Pure string work over a URL's path space. Nothing here knows about docs,
+ * versions or pages; the domain meaning lives in `core/`, which calls in.
+ */
+/**
+ * Strip a trailing slash so route matching is consistent regardless of the
+ * consumer's SvelteKit `trailingSlash` setting: `/docs/intro/` and `/docs/intro`
+ * resolve to the same content entry. The root stays `/`.
+ */
+export function normalizePath(pathname) {
+    return pathname.replace(/\/+$/, '') || '/';
+}
+/**
+ * A base as a string prefix. The site root addresses everything, so it has no
+ * prefix: spelled `/`, the boundary check below would look for `//`. `''` and
+ * `/` are therefore the same base, and callers may pass whichever they hold.
+ * Reachable through `docsBaseFrom` when a site puts its docs at the routes root.
+ */
+function baseAsPrefix(base) {
+    return base === '/' ? '' : base;
+}
+/**
+ * True when nothing follows a base, or what follows starts a new segment rather
+ * than continuing the last one. `?` and `#` count, so the rule holds for a link
+ * href as well as a pathname; that is what stops `/docs` from matching
+ * `/docsmith`.
+ *
+ * Exported for the one caller that has already sliced the base off itself: the
+ * archive link rewriter matches its base with a regex and needs the remainder
+ * afterwards, so it checks the boundary rather than re-testing the whole URL.
+ */
+export function atBoundary(rest) {
+    return rest === '' || /^[/#?]/.test(rest);
+}
+/** True when `url` is `base` or sits beneath it on a segment boundary. */
+export function under(url, base) {
+    const b = baseAsPrefix(base);
+    return url.startsWith(b) && atBoundary(url.slice(b.length));
+}
+/**
+ * The one segment directly below `base`, which is what decides who owns a URL:
+ * an archived version owns `<docs base>/<id>/…`, and a header link owns its
+ * whole first-segment section. `undefined` when `url` is not under `base` at
+ * all, or when the base is the end of it, so callers must handle "no segment"
+ * rather than interpolate it into a path.
+ */
+export function firstSegmentUnder(url, base) {
+    if (!under(url, base))
+        return undefined;
+    const rest = url.slice(baseAsPrefix(base).length);
+    if (!rest.startsWith('/'))
+        return undefined;
+    return rest.slice(1).split(/[/#?]/)[0] || undefined;
+}
+/**
+ * Join two URL pieces with exactly one slash between them, whichever of them
+ * already carries it. Use it for every URL built from a configured origin or
+ * base, so a trailing slash in someone's config can never double up.
+ *
+ * Only the seam between the two is touched, never the rest of either: rescanning
+ * would turn `https://x.dev` into `https:/x.dev`. Nor is the result normalized,
+ * so `join(origin, '/')` still ends in a slash and a sitemap can carry the home
+ * page.
+ *
+ * An empty `left` returns `right` untouched, which is what an unconfigured
+ * origin needs: `llms.txt` and the copy-page menu fall back to site-relative
+ * links rather than emitting a stray leading slash. Callers that must not degrade
+ * to a relative URL, like `<link rel="canonical">`, have to check the origin
+ * themselves.
+ */
+export function join(left, right) {
+    if (!left)
+        return right;
+    const l = left.replace(/\/+$/, '');
+    if (!right)
+        return l || '/';
+    return l + '/' + right.replace(/^\/+/, '');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-docsmith",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "A framework for building beautiful documentation sites with Svelte.",
   "author": {
     "name": "George Daskalakis",

package/dist/utils/normalize-path.d.ts

@@ -1,6 +0,0 @@
-/**
- * Strip a trailing slash so route matching is consistent regardless of the
- * consumer's SvelteKit `trailingSlash` setting: `/docs/intro/` and `/docs/intro`
- * resolve to the same content entry. The root stays `/`.
- */
-export declare function normalizePath(pathname: string): string;

package/dist/utils/normalize-path.js

@@ -1,8 +0,0 @@
-/**
- * Strip a trailing slash so route matching is consistent regardless of the
- * consumer's SvelteKit `trailingSlash` setting: `/docs/intro/` and `/docs/intro`
- * resolve to the same content entry. The root stays `/`.
- */
-export function normalizePath(pathname) {
-    return pathname.replace(/\/+$/, '') || '/';
-}