svelte-docsmith 0.1.0

package/dist/ui/table-of-contents.svelte

@@ -0,0 +1,114 @@
+<script lang="ts">
+	import { cn } from '../shadcn.js';
+	import type { TocItem } from '../toc/index.js';
+	import List from '@lucide/svelte/icons/list';
+
+	const {
+		items = [],
+		activeId = null,
+		class: className = ''
+	}: {
+		items?: TocItem[];
+		activeId?: string | null;
+		class?: string;
+	} = $props();
+
+	// The single primary marker slides along the rail to the active entry. We
+	// measure the active anchor's box and animate the marker to it.
+	let railEl = $state<HTMLElement | null>(null);
+	let markerTop = $state(0);
+	let markerHeight = $state(0);
+	// Gate the transition so the first placement snaps instead of sliding in.
+	let animate = $state(false);
+
+	$effect(() => {
+		const id = activeId;
+		void items; // re-measure when the heading set changes
+		if (!railEl || !id) {
+			markerHeight = 0;
+			return;
+		}
+		const target = railEl.querySelector<HTMLElement>(`[data-toc-id="${CSS.escape(id)}"]`);
+		if (!target) {
+			markerHeight = 0;
+			return;
+		}
+		markerTop = target.offsetTop;
+		markerHeight = target.offsetHeight;
+		if (!animate) requestAnimationFrame(() => (animate = true));
+	});
+</script>
+
+{#if items.length > 0}
+	<aside class={cn('sticky top-24 self-start', className)}>
+		<nav aria-label="On this page" class="pr-2">
+			<p class="text-foreground mb-3 flex items-center gap-2 text-sm font-semibold">
+				<List class="size-4" />
+				On this page
+			</p>
+			<div bind:this={railEl} class="toc-rail max-h-[calc(100vh-16rem)] overflow-y-auto text-sm">
+				<span
+					class="toc-marker"
+					class:toc-marker-animate={animate}
+					style="transform: translateY({markerTop}px); height: {markerHeight}px; opacity: {markerHeight >
+					0
+						? 1
+						: 0};"
+					aria-hidden="true"
+				></span>
+				<ul>
+					{#each items as item (item.id)}
+						<li>
+							<a
+								href="#{item.id}"
+								data-toc-id={item.id}
+								aria-current={activeId === item.id ? 'location' : undefined}
+								class={cn(
+									'text-muted-foreground hover:text-foreground block py-1.5 pl-4 leading-snug transition-colors duration-150',
+									item.depth === 3 && 'pl-8',
+									activeId === item.id && 'text-primary font-medium'
+								)}
+							>
+								{item.title}
+							</a>
+						</li>
+					{/each}
+				</ul>
+			</div>
+		</nav>
+	</aside>
+{/if}
+
+<style>
+	/* The faint full-height rail; the marker is the bright segment on top of it. */
+	.toc-rail {
+		position: relative;
+		border-left: 1px solid var(--border);
+	}
+	.toc-rail ul {
+		margin: 0;
+		padding: 0;
+		list-style: none;
+	}
+	.toc-marker {
+		position: absolute;
+		left: -1px;
+		top: 0;
+		width: 2px;
+		border-radius: 1px;
+		background: var(--primary);
+		/* Placement is set inline; only animate once past the first frame. */
+		will-change: transform, height;
+	}
+	.toc-marker-animate {
+		transition:
+			transform 280ms cubic-bezier(0.22, 1, 0.36, 1),
+			height 280ms cubic-bezier(0.22, 1, 0.36, 1),
+			opacity 160ms ease;
+	}
+	@media (prefers-reduced-motion: reduce) {
+		.toc-marker-animate {
+			transition: opacity 160ms ease;
+		}
+	}
+</style>

package/dist/ui/table-of-contents.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { TocItem } from '../toc/index.js';
+type $$ComponentProps = {
+    items?: TocItem[];
+    activeId?: string | null;
+    class?: string;
+};
+declare const TableOfContents: import("svelte").Component<$$ComponentProps, {}, "">;
+type TableOfContents = ReturnType<typeof TableOfContents>;
+export default TableOfContents;

package/dist/ui/tabs.svelte

@@ -0,0 +1,29 @@
+<script lang="ts">
+	import * as Tabs from './shadcn/tabs/index.js';
+	import type { WithChildren } from '../types.js';
+
+	type TabsProps = {
+		items: string[];
+		value: string;
+	};
+
+	const { children, items, value = items[0] }: WithChildren<TabsProps> = $props();
+</script>
+
+<Tabs.Root class="my-6" {value}>
+	<Tabs.List class="not-prose mb-3">
+		{#each items as item (item)}
+			<!-- bits-ui v2 emits data-state="active"; the vendored trigger styles the
+			     active state with data-active (a skew from the CLI's registry version),
+			     so paint the active state here to match what's actually emitted. -->
+			<Tabs.Trigger
+				value={item}
+				class="data-[state=active]:bg-background data-[state=active]:text-foreground data-[state=active]:shadow-sm"
+			>
+				{item}
+			</Tabs.Trigger>
+		{/each}
+	</Tabs.List>
+
+	{@render children()}
+</Tabs.Root>

package/dist/ui/tabs.svelte.d.ts

@@ -0,0 +1,8 @@
+import * as Tabs from './shadcn/tabs/index.js';
+import type { WithChildren } from '../types.js';
+declare const Tabs: import("svelte").Component<WithChildren<{
+    items: string[];
+    value: string;
+}>, {}, "">;
+type Tabs = ReturnType<typeof Tabs>;
+export default Tabs;

package/dist/ui/theme-provider.svelte

@@ -0,0 +1,23 @@
+<script lang="ts">
+	import { ModeWatcher } from 'mode-watcher';
+	import type { Snippet } from 'svelte';
+
+	const {
+		children,
+		disableTransitions = true
+	}: {
+		/** App content. Optional — the provider works as a bare `<ThemeProvider />` too. */
+		children?: Snippet;
+		/** Suppress the color transition on theme change (avoids a flash). */
+		disableTransitions?: boolean;
+	} = $props();
+</script>
+
+<!--
+	Owns light/dark for the whole app: mounts mode-watcher, which toggles the
+	`.dark` class on <html> and persists the choice. `DocsShell` renders this
+	internally, so a consumer never installs or wires mode-watcher themselves.
+	Use it directly to wrap non-DocsShell pages (a marketing/landing route).
+-->
+<ModeWatcher {disableTransitions} />
+{#if children}{@render children()}{/if}

package/dist/ui/theme-provider.svelte.d.ts

@@ -0,0 +1,10 @@
+import type { Snippet } from 'svelte';
+type $$ComponentProps = {
+    /** App content. Optional — the provider works as a bare `<ThemeProvider />` too. */
+    children?: Snippet;
+    /** Suppress the color transition on theme change (avoids a flash). */
+    disableTransitions?: boolean;
+};
+declare const ThemeProvider: import("svelte").Component<$$ComponentProps, {}, "">;
+type ThemeProvider = ReturnType<typeof ThemeProvider>;
+export default ThemeProvider;

package/dist/ui/theme-toggle.svelte

@@ -0,0 +1,22 @@
+<script lang="ts">
+	import { Button } from './shadcn/button/index.js';
+	import Moon from '@lucide/svelte/icons/moon';
+	import Sun from '@lucide/svelte/icons/sun';
+	import { mode, toggleMode } from 'mode-watcher';
+
+	const { class: className }: { class?: string } = $props();
+</script>
+
+<Button
+	size="icon"
+	variant="ghost"
+	onclick={toggleMode}
+	class="text-muted-foreground hover:text-foreground size-8 {className ?? ''}"
+>
+	{#if mode.current === 'dark'}
+		<Sun class="size-4" />
+	{:else}
+		<Moon class="size-4" />
+	{/if}
+	<span class="sr-only">Toggle theme</span>
+</Button>

package/dist/ui/theme-toggle.svelte.d.ts

@@ -0,0 +1,6 @@
+type $$ComponentProps = {
+    class?: string;
+};
+declare const ThemeToggle: import("svelte").Component<$$ComponentProps, {}, "">;
+type ThemeToggle = ReturnType<typeof ThemeToggle>;
+export default ThemeToggle;

package/dist/vite.d.ts

@@ -0,0 +1,32 @@
+import type { Plugin } from 'vite';
+import type { DocsContentItem } from './config.js';
+export interface DocsmithViteOptions {
+    /** Directory scanned for doc pages. Default: `'src/routes/docs'`. */
+    content?: string;
+    /**
+     * Routes root used to derive each page's URL from its location.
+     * Default: `'src/routes'` (so `src/routes/docs/intro/+page.md` → `/docs/intro`).
+     */
+    routes?: string;
+    /** Shiki themes for the `?source` render. Default: github-light/github-dark. */
+    themes?: {
+        light: string;
+        dark: string;
+    };
+}
+/**
+ * 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 declare function docsmith(options?: DocsmithViteOptions): Plugin[];
+/**
+ * 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),
+ * deriving each page's URL from its directory relative to `routesDir`. Pure and
+ * synchronous so it can be unit-tested.
+ */
+export declare function collectDocs(contentDir: string, routesDir: string): DocsContentItem[];

package/dist/vite.js

@@ -0,0 +1,216 @@
+/**
+ * `svelte-docsmith/vite` — the build-time half of the framework. Node context
+ * only. One `docsmith()` call in `vite.config.ts` wires two 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 velite, no collection
+ *     config, no aliases.
+ *  2. The **`?source` transform** powering `LiveExample`: importing
+ *     `Component.svelte?source` yields that file's Shiki-highlighted source.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+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 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;
+}
+/** Slugify heading text the way rehype-slug (github-slugger) does for common
+ *  cases: lowercase, drop punctuation/symbols, spaces → hyphens. */
+function slugify(text) {
+    return text
+        .trim()
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}\s-]/gu, '')
+        .replace(/\s+/g, '-');
+}
+/** 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, '')
+        .trim();
+}
+/**
+ * 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
+ * match rehype-slug for typical headings, and the runtime engine's DOM re-scan
+ * corrects any edge cases after hydration.
+ */
+function extractToc(source) {
+    const body = source.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '');
+    const seen = new Map();
+    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;
+        const base = slugify(title);
+        const n = seen.get(base) ?? 0;
+        seen.set(base, n + 1);
+        toc.push({ id: n > 0 ? `${base}-${n}` : base, title, depth: m[1].length });
+    }
+    return toc;
+}
+/**
+ * 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),
+ * deriving each page's URL from its directory relative to `routesDir`. Pure and
+ * synchronous so it can be unit-tested.
+ */
+export function collectDocs(contentDir, routesDir) {
+    const items = [];
+    for (const file of listPageFiles(contentDir)) {
+        const source = fs.readFileSync(file, 'utf-8');
+        const front = parseFrontmatter(source);
+        if (typeof front.title !== 'string')
+            continue; // a page without a title isn't nav-worthy
+        const dir = path.dirname(file);
+        const url = '/' + path.relative(routesDir, dir).split(path.sep).join('/');
+        items.push({
+            title: front.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,
+            toc: extractToc(source)
+        });
+    }
+    // Stable output keeps the generated module diff-friendly across rebuilds.
+    return items.sort((a, b) => a.path.localeCompare(b.path));
+}
+function parseFrontmatter(source) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(source);
+    if (!match)
+        return {};
+    const data = yaml.load(match[1]);
+    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;
+        },
+        load(id) {
+            if (id !== VIRTUAL_CONTENT_ID)
+                return;
+            // Watch each page file (not the directory) so editing frontmatter
+            // 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.
+            for (const file of listPageFiles(contentDir))
+                this.addWatchFile(file);
+            const docs = collectDocs(contentDir, routesDir);
+            return `export const docs = ${JSON.stringify(docs, null, 2)};\n`;
+        },
+        configureServer(server) {
+            server.watcher.add(contentDir);
+            const onChange = (file) => {
+                if (!isPageFile(file))
+                    return;
+                const mod = server.moduleGraph.getModuleById(VIRTUAL_CONTENT_ID);
+                if (!mod)
+                    return;
+                server.moduleGraph.invalidateModule(mod);
+                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)};`;
+        }
+    };
+}

package/package.json

@@ -0,0 +1,115 @@
+{
+  "name": "svelte-docsmith",
+  "version": "0.1.0",
+  "description": "A framework for building beautiful documentation sites with Svelte.",
+  "author": {
+    "name": "George Daskalakis",
+    "email": "george.dask97@gmail.com",
+    "url": "https://github.com/geodask"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "!dist/**/*.spec.*"
+  ],
+  "sideEffects": false,
+  "svelte": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "svelte": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./preprocess": {
+      "types": "./dist/preprocess.d.ts",
+      "default": "./dist/preprocess.js"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "default": "./dist/vite.js"
+    },
+    "./content": {
+      "types": "./dist/content.d.ts",
+      "default": "./dist/content.js"
+    },
+    "./theme.css": "./dist/theme.css",
+    "./themes/*.css": "./dist/themes/*.css",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/geodask/svelte-docsmith.git"
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@sveltejs/kit": "^2.16.0",
+    "svelte": "^5.0.0",
+    "tailwindcss": "^4.0.0"
+  },
+  "devDependencies": {
+    "@fontsource-variable/inter": "^5.2.8",
+    "@internationalized/date": "^3.12.2",
+    "@lucide/svelte": "^1.23.0",
+    "@sveltejs/adapter-auto": "^7.0.1",
+    "@sveltejs/adapter-vercel": "^6.3.4",
+    "@sveltejs/kit": "^2.69.1",
+    "@sveltejs/package": "^2.5.8",
+    "@sveltejs/vite-plugin-svelte": "^7.1.2",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/svelte": "^5.2.4",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22",
+    "@vitest/coverage-v8": "4.1.9",
+    "clsx": "^2.1.1",
+    "jsdom": "^26.0.0",
+    "publint": "^0.3.2",
+    "shadcn-svelte": "^1.3.0",
+    "svelte": "^5.56.4",
+    "svelte-check": "^4.7.1",
+    "tailwind-merge": "^3.6.0",
+    "tailwind-variants": "^3.2.2",
+    "tailwindcss": "^4.3.2",
+    "tw-animate-css": "^1.4.0",
+    "typescript": "^5.0.0",
+    "vite": "^8.1.3",
+    "vitest": "^4.1.9"
+  },
+  "dependencies": {
+    "@hbsnow/rehype-sectionize": "^1.0.7",
+    "@shikijs/transformers": "^3.3.0",
+    "@tailwindcss/typography": "^0.5.16",
+    "bits-ui": "^2.18.1",
+    "esm-env": "^1.2.2",
+    "js-yaml": "^4.1.0",
+    "mdsvex": "^0.12.3",
+    "mode-watcher": "^1.0.2",
+    "rehype-slug": "^6.0.0",
+    "shiki": "^3.2.2"
+  },
+  "keywords": [
+    "svelte",
+    "ui",
+    "component",
+    "docs"
+  ],
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build && npm run prepack",
+    "preview": "vite preview",
+    "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+    "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
+    "format": "prettier --config ../../.prettierrc --write .",
+    "lint": "prettier --config ../../.prettierrc --check . && eslint .",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:unit": "vitest run",
+    "typecheck": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+    "size": "size-limit"
+  }
+}