svelte-docsmith 0.5.1 → 0.7.0

package/dist/config.d.ts

@@ -1,141 +0,0 @@
-/**
- * Static site configuration passed to `DocsShell`. Content-derived data (the
- * sidebar nav) is NOT here — it comes from your content collection at runtime.
- */
-/** A link rendered in the header nav or footer. */
-export type DocsmithLink = {
-    label: string;
-    href: string;
-    /** Open in a new tab with `rel="noopener"`. */
-    external?: boolean;
-};
-/** A titled column of links in the footer. */
-export type DocsmithFooterColumn = {
-    title: string;
-    links: DocsmithLink[];
-};
-export type DocsmithConfig = {
-    /** Site title, shown in the header/sidebar and in the `<title>` suffix. */
-    title: string;
-    /**
-     * Default meta description, used for pages whose frontmatter has none (and
-     * as the site's social-share description).
-     */
-    description?: string;
-    /**
-     * Canonical site origin, e.g. `https://docs.example.com`. When set, DocsShell
-     * emits `<link rel="canonical">` and absolute Open Graph URLs.
-     */
-    url?: string;
-    /** Default social-share image (absolute URL, or a path resolved against `url`). */
-    ogImage?: string;
-    /**
-     * Base URL for the "Edit this page" link, pointing at the directory that maps
-     * to your app's working directory in the repo, e.g.
-     * `https://github.com/you/repo/edit/main/apps/docs`. DocsShell appends each
-     * page's source path. Omit to hide the edit link.
-     */
-    editUrl?: string;
-    /** Optional GitHub URL; renders a link in the header when set. */
-    github?: string;
-    /** Optional version string, shown in the header (e.g. your library version). */
-    version?: string;
-    /** Optional logo image src; falls back to the built-in book mark. */
-    logo?: string;
-    /** Top-level header navigation links. */
-    nav?: DocsmithLink[];
-    /** Footer content, driven by data. */
-    footer?: {
-        /** Copyright / attribution line. */
-        copyright?: string;
-        /** Titled columns of links. */
-        columns?: DocsmithFooterColumn[];
-        /**
-         * Show the "Powered by Svelte DocSmith" attribution in the footer.
-         * Defaults to `true`; set `false` to hide it.
-         */
-        poweredBy?: boolean;
-    };
-};
-/**
- * Validate a {@link DocsmithConfig} at build time. Purely a pass-through for
- * typed callers; the runtime checks catch untyped or dynamically-built configs
- * with a real error message instead of a blank header.
- */
-export declare function defineConfig(config: DocsmithConfig): DocsmithConfig;
-/**
- * The minimal shape `DocsShell` needs from each content entry to build the
- * sidebar. The generated `svelte-docsmith/content` module produces these from
- * your pages' frontmatter; any source with matching title/path/section/order
- * fields satisfies it structurally.
- */
-export type DocsContentItem = {
-    title: string;
-    path: string;
-    section?: string;
-    order?: number;
-    description?: string;
-    /** Source file path relative to the app cwd, for the "Edit this page" link. */
-    sourcePath?: string;
-    /** Last git commit date (ISO) for the page's source file. */
-    lastUpdated?: string;
-    /**
-     * The page's `h2`/`h3` headings, extracted at build time by the `docsmith()`
-     * vite plugin, so `DocsShell` can render the in-page TOC server-side. The
-     * runtime TOC engine still owns scroll-spy and re-scans the DOM.
-     */
-    toc?: {
-        id: string;
-        title: string;
-        depth: 2 | 3;
-    }[];
-};
-/**
- * One page's searchable record, emitted at build time by the `docsmith()` vite
- * plugin as the `svelte-docsmith/search` virtual module. `text` is the page's
- * prose and headings reduced to plain text (frontmatter, `<script>` blocks,
- * fenced code, tags, and markdown punctuation stripped) so a client-side search
- * index can be built over it without shipping raw markdown.
- */
-export type SearchDoc = {
-    path: string;
-    title: string;
-    section?: string;
-    description?: string;
-    /** The page's `h2`/`h3` heading text, for weighting title/heading matches. */
-    headings: string[];
-    /** Plain-text body: prose and headings, code and markup removed. */
-    text: string;
-};
-/**
- * One page's record for LLM-facing output, emitted at build time by the
- * `docsmith()` vite plugin as the `svelte-docsmith/llms` virtual module. Feeds
- * `generateLlmsTxt` (an index) and `generateLlmsFullTxt` (the full corpus).
- */
-export type LlmsDoc = {
-    path: string;
-    title: string;
-    section?: string;
-    /** Sidebar order within the section, so LLM output follows reading order. */
-    order?: number;
-    description?: string;
-    /** The page's markdown body (frontmatter and `<script>`/`<style>` removed,
-     *  headings and code kept), with the title prepended as an `h1`. */
-    content: string;
-};
-/** A single sidebar link. */
-export type NavItem = {
-    title: string;
-    url: string;
-};
-/** A titled group of sidebar links. */
-export type NavGroup = {
-    title: string;
-    items: NavItem[];
-};
-/**
- * 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".
- */
-export declare function navFromContent(content: DocsContentItem[]): NavGroup[];

package/dist/content.js

@@ -1,4 +0,0 @@
-export const docs = [];
-throw new Error("[svelte-docsmith] 'svelte-docsmith/content' requires the docsmith() plugin. " +
-    "Add it to your vite.config: import { docsmith } from 'svelte-docsmith/vite'; " +
-    'plugins: [docsmith(), tailwindcss(), sveltekit()]');

package/dist/llms.js

@@ -1,4 +0,0 @@
-export const docs = [];
-throw new Error("[svelte-docsmith] 'svelte-docsmith/llms' requires the docsmith() plugin. " +
-    "Add it to your vite.config: import { docsmith } from 'svelte-docsmith/vite'; " +
-    'plugins: [docsmith(), tailwindcss(), sveltekit()]');

package/dist/search.js

@@ -1,4 +0,0 @@
-export const docs = [];
-throw new Error("[svelte-docsmith] 'svelte-docsmith/search' requires the docsmith() plugin. " +
-    "Add it to your vite.config: import { docsmith } from 'svelte-docsmith/vite'; " +
-    'plugins: [docsmith(), tailwindcss(), sveltekit()]');

package/dist/vite.js

@@ -1,366 +0,0 @@
-/**
- * `svelte-docsmith/vite` — the build-time half of the framework. Node context
- * only. One `docsmith()` call in `vite.config.ts` wires three things:
- *
- *  1. A **content index** served as the virtual module `svelte-docsmith/content`
- *     — your doc pages' frontmatter, scanned at build time, so the sidebar nav
- *     is derived from content and never hand-written. No collection config, no
- *     aliases.
- *  2. A **search index** served as the virtual module `svelte-docsmith/search`
- *     — the same pages reduced to plain-text bodies, in a separate chunk so it
- *     can be lazy-loaded only when search opens.
- *  3. The **`?source` transform** powering `LiveExample`: importing
- *     `Component.svelte?source` yields that file's Shiki-highlighted source.
- */
-import { spawnSync } from 'node:child_process';
-import fs from 'node:fs';
-import path from 'node:path';
-import GithubSlugger from 'github-slugger';
-import yaml from 'js-yaml';
-import { DEFAULT_THEMES, lazyHighlighter } from './highlight.js';
-/**
- * The svelte-docsmith Vite plugin. Add it to `plugins` in `vite.config.ts`:
- *
- * ```ts
- * import { docsmith } from 'svelte-docsmith/vite';
- * export default defineConfig({ plugins: [docsmith(), tailwindcss(), sveltekit()] });
- * ```
- */
-export function docsmith(options = {}) {
-    return [contentIndexPlugin(options), exampleSourcePlugin(options)];
-}
-// --- content index -------------------------------------------------------
-const CONTENT_SPECIFIER = 'svelte-docsmith/content';
-const VIRTUAL_CONTENT_ID = '\0svelte-docsmith:content';
-const SEARCH_SPECIFIER = 'svelte-docsmith/search';
-const VIRTUAL_SEARCH_ID = '\0svelte-docsmith:search';
-const LLMS_SPECIFIER = 'svelte-docsmith/llms';
-const VIRTUAL_LLMS_ID = '\0svelte-docsmith:llms';
-const PAGE_NAMES = ['+page.md', '+page.svx'];
-function isPageFile(file) {
-    return PAGE_NAMES.some((name) => file.endsWith(name));
-}
-/**
- * List the absolute paths of every `+page.md`/`+page.svx` under `contentDir`.
- */
-function listPageFiles(contentDir) {
-    if (!fs.existsSync(contentDir))
-        return [];
-    const entries = fs.readdirSync(contentDir, { recursive: true, withFileTypes: true });
-    const files = [];
-    for (const entry of entries) {
-        if (!entry.isFile() || !isPageFile(entry.name))
-            continue;
-        const dir = entry.parentPath ?? entry.path ?? contentDir;
-        files.push(path.join(dir, entry.name));
-    }
-    return files;
-}
-/** Strip inline markdown so a heading's TOC label is plain text. */
-function stripInlineMarkdown(text) {
-    return text
-        .replace(/!\[([^\]]*)\]\([^)]*\)/g, '$1')
-        .replace(/`([^`]+)`/g, '$1')
-        .replace(/\*\*([^*]+)\*\*/g, '$1')
-        .replace(/\*([^*]+)\*/g, '$1')
-        .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
-        .replace(/[_~]/g, '')
-        .trim();
-}
-/**
- * Reduce a markdown page to plain, searchable body text: prose and heading text
- * with frontmatter, `<script>`/`<style>` blocks, fenced code, HTML/Svelte tags,
- * and markdown punctuation removed. Feeds the generated search index. Code
- * samples are intentionally dropped to keep the index small and prose-focused.
- */
-function extractSearchText(source) {
-    let body = source.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '');
-    // Component/setup blocks aren't prose; drop them whole before line scanning.
-    body = body.replace(/<script[\s\S]*?<\/script>/gi, '').replace(/<style[\s\S]*?<\/style>/gi, '');
-    const out = [];
-    let fence = null;
-    for (const line of body.split('\n')) {
-        const f = /^\s*(`{3,}|~{3,})/.exec(line);
-        if (f) {
-            const ch = f[1][0];
-            if (fence === null)
-                fence = ch;
-            else if (ch === fence)
-                fence = null;
-            continue;
-        }
-        if (fence !== null)
-            continue;
-        // Skip table delimiter rows (`| --- | :--: |`) — pure structure, no words.
-        if (/^\s*\|?[\s:|-]+\|[\s:|-]*$/.test(line))
-            continue;
-        const text = stripInlineMarkdown(line
-            .replace(/<[^>]+>/g, ' ') // strip HTML/Svelte tags, keep their text content
-            .replace(/^\s{0,3}#{1,6}\s+/, '') // heading markers
-            .replace(/^\s{0,3}>\s?/, '') // blockquote markers
-            .replace(/^\s*[-*+]\s+/, '') // unordered list bullets
-            .replace(/^\s*\d+\.\s+/, '') // ordered list markers
-            .replace(/\s*\|\s*/g, ' ') // table cell separators → spaces, not "| a | b |"
-        ).replace(/\s+/g, ' ');
-        if (text)
-            out.push(text);
-    }
-    return out.join(' ');
-}
-/**
- * Extract `h2`/`h3` headings from a markdown page so the in-page TOC can be
- * server-rendered (no post-hydration pop-in). Skips fenced code blocks. Ids are
- * produced with the same `github-slugger` that `rehype-slug` uses at render
- * time — including its duplicate-suffixing — so the SSR anchors match the real
- * heading ids exactly, not just for common cases.
- */
-function extractToc(source) {
-    const body = source.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '');
-    const slugger = new GithubSlugger();
-    const toc = [];
-    let fence = null;
-    for (const line of body.split('\n')) {
-        const f = /^\s*(`{3,}|~{3,})/.exec(line);
-        if (f) {
-            const ch = f[1][0];
-            if (fence === null)
-                fence = ch;
-            else if (ch === fence)
-                fence = null;
-            continue;
-        }
-        if (fence !== null)
-            continue;
-        const m = /^(#{2,3})\s+(.+?)\s*#*\s*$/.exec(line);
-        if (!m)
-            continue;
-        const title = stripInlineMarkdown(m[2]);
-        if (!title)
-            continue;
-        toc.push({ id: slugger.slug(title), title, depth: m[1].length });
-    }
-    return toc;
-}
-/** Last git commit date (strict ISO) for a file, or undefined outside a repo. */
-function lastCommitDate(file) {
-    const res = spawnSync('git', ['log', '-1', '--format=%cI', '--', file], {
-        cwd: path.dirname(file),
-        encoding: 'utf-8'
-    });
-    const date = res.status === 0 ? res.stdout.trim() : '';
-    return date || undefined;
-}
-/**
- * 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 both the nav index and the search
- * index can be built from a single read of each file.
- */
-function* eachTitledPage(contentDir, routesDir) {
-    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 };
-    }
-}
-export function collectDocs(contentDir, routesDir) {
-    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 } of eachTitledPage(contentDir, routesDir)) {
-        items.push({
-            title,
-            path: url,
-            description: typeof front.description === 'string' ? front.description : undefined,
-            section: typeof front.section === 'string' ? front.section : undefined,
-            order: typeof front.order === 'number' ? front.order : undefined,
-            sourcePath: path.relative(process.cwd(), file).split(path.sep).join('/'),
-            lastUpdated: lastCommitDate(file),
-            toc: extractToc(source)
-        });
-    }
-    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));
-}
-/**
- * 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.
- */
-export function collectSearchDocs(contentDir, routesDir) {
-    if (!fs.existsSync(contentDir))
-        return [];
-    const docs = [];
-    for (const { source, front, url, title } of eachTitledPage(contentDir, routesDir)) {
-        docs.push({
-            path: url,
-            title,
-            section: typeof front.section === 'string' ? front.section : undefined,
-            description: typeof front.description === 'string' ? front.description : undefined,
-            headings: extractToc(source).map((entry) => entry.title),
-            text: extractSearchText(source)
-        });
-    }
-    return docs.sort((a, b) => a.path.localeCompare(b.path));
-}
-/**
- * The page's markdown body for LLM output: frontmatter and `<script>`/`<style>`
- * blocks removed, everything else (headings, prose, code, component tags) kept,
- * with the frontmatter title prepended as an `h1` (pages start their body at h2).
- */
-function extractLlmsContent(source, title) {
-    const body = source
-        .replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '')
-        .replace(/<script[\s\S]*?<\/script>/gi, '')
-        .replace(/<style[\s\S]*?<\/style>/gi, '')
-        .trim();
-    return `# ${title}\n\n${body}`;
-}
-/**
- * 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.
- */
-export function collectLlmsDocs(contentDir, routesDir) {
-    if (!fs.existsSync(contentDir))
-        return [];
-    const docs = [];
-    for (const { source, front, url, title } of eachTitledPage(contentDir, routesDir)) {
-        docs.push({
-            path: url,
-            title,
-            section: typeof front.section === 'string' ? front.section : undefined,
-            order: typeof front.order === 'number' ? front.order : undefined,
-            description: typeof front.description === 'string' ? front.description : undefined,
-            content: extractLlmsContent(source, title)
-        });
-    }
-    return docs.sort((a, b) => a.path.localeCompare(b.path));
-}
-function parseFrontmatter(source, file) {
-    const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(source);
-    if (!match)
-        return {};
-    let data;
-    try {
-        data = yaml.load(match[1]);
-    }
-    catch (err) {
-        const reason = err instanceof Error ? err.message : String(err);
-        throw new Error(`[svelte-docsmith] invalid YAML frontmatter in ${file}\n${reason}`);
-    }
-    return data && typeof data === 'object' ? data : {};
-}
-function contentIndexPlugin(options) {
-    const contentDir = path.resolve(options.content ?? 'src/routes/docs');
-    const routesDir = path.resolve(options.routes ?? 'src/routes');
-    return {
-        name: 'docsmith-content',
-        enforce: 'pre',
-        resolveId(id) {
-            if (id === CONTENT_SPECIFIER)
-                return VIRTUAL_CONTENT_ID;
-            if (id === SEARCH_SPECIFIER)
-                return VIRTUAL_SEARCH_ID;
-            if (id === LLMS_SPECIFIER)
-                return VIRTUAL_LLMS_ID;
-        },
-        load(id) {
-            // Watch each page file (not the directory) so editing frontmatter or
-            // 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.
-            if (id === VIRTUAL_CONTENT_ID) {
-                for (const file of listPageFiles(contentDir))
-                    this.addWatchFile(file);
-                const docs = collectDocs(contentDir, routesDir);
-                return `export const docs = ${JSON.stringify(docs, null, 2)};\n`;
-            }
-            if (id === VIRTUAL_SEARCH_ID) {
-                for (const file of listPageFiles(contentDir))
-                    this.addWatchFile(file);
-                const docs = collectSearchDocs(contentDir, routesDir);
-                return `export const docs = ${JSON.stringify(docs)};\n`;
-            }
-            if (id === VIRTUAL_LLMS_ID) {
-                for (const file of listPageFiles(contentDir))
-                    this.addWatchFile(file);
-                const docs = collectLlmsDocs(contentDir, routesDir);
-                return `export const docs = ${JSON.stringify(docs)};\n`;
-            }
-        },
-        configureServer(server) {
-            server.watcher.add(contentDir);
-            const onChange = (file) => {
-                if (!isPageFile(file))
-                    return;
-                let invalidated = false;
-                for (const virtualId of [VIRTUAL_CONTENT_ID, VIRTUAL_SEARCH_ID, VIRTUAL_LLMS_ID]) {
-                    const mod = server.moduleGraph.getModuleById(virtualId);
-                    if (!mod)
-                        continue;
-                    server.moduleGraph.invalidateModule(mod);
-                    invalidated = true;
-                }
-                if (invalidated)
-                    server.ws.send({ type: 'full-reload' });
-            };
-            server.watcher.on('add', onChange);
-            server.watcher.on('unlink', onChange);
-            server.watcher.on('change', onChange);
-        }
-    };
-}
-// --- ?source transform (LiveExample) ------------------------------------
-const SOURCE_PREFIX = '\0docsmith-source:';
-// The virtual id must NOT end in `.svelte`, or vite-plugin-svelte will try to
-// compile the highlighted-HTML string as a component.
-const SOURCE_EXT = '.docsmith-src';
-const SOURCE_SUFFIX = '?source';
-function exampleSourcePlugin(options) {
-    const themes = options.themes ?? DEFAULT_THEMES;
-    const getHighlighter = lazyHighlighter([themes.light, themes.dark], ['svelte']);
-    return {
-        name: 'docsmith-example-source',
-        enforce: 'pre',
-        async resolveId(id, importer) {
-            if (!id.endsWith('.svelte' + SOURCE_SUFFIX))
-                return;
-            const base = id.slice(0, -SOURCE_SUFFIX.length);
-            const resolved = await this.resolve(base, importer, { skipSelf: true });
-            if (resolved)
-                return SOURCE_PREFIX + resolved.id + SOURCE_EXT;
-        },
-        async load(id) {
-            if (!id.startsWith(SOURCE_PREFIX))
-                return;
-            const file = id.slice(SOURCE_PREFIX.length, -SOURCE_EXT.length);
-            this.addWatchFile(file);
-            const code = fs.readFileSync(file, 'utf-8').trimEnd();
-            const highlighter = await getHighlighter();
-            // Strip Shiki's own surface (the inline light `background-color` and the
-            // `--shiki-dark-bg` var) so the highlighted source sits on the
-            // consuming component's token background — matching markdown code blocks,
-            // and never flashing Shiki's default before component CSS applies.
-            const html = highlighter
-                .codeToHtml(code, { lang: 'svelte', themes })
-                .replace(/background-color:[^;"]*;?/gi, '')
-                .replace(/--shiki-dark-bg:[^;"]*;?/gi, '');
-            return `export default ${JSON.stringify(html)};`;
-        }
-    };
-}