sdocs 0.0.59 → 0.0.61

package/CHANGELOG.md

@@ -7,6 +7,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.61] - 2026-07-06
+
+### Added
+
+- **Sections: full documentation sites in the Explorer.** An `@Section/`
+  prefix on any entity title (`[PAGE title="@Guides/Installation"]`) groups
+  docs under a full-width top bar, each section with its own sidebar — mix
+  pages-only sections with component sections freely. Docs without a prefix
+  land in a configurable default section (`defaultSection`, default
+  `Docs`); the bar only appears once a second section exists, so existing
+  projects look unchanged. Tab order comes from the new `sections` config
+  (unlisted sections follow alphabetically).
+- **Real URLs (history routing).** Doc routes are now slugified paths —
+  `/components/button/sizes` instead of `#/Components/Button/Sizes`. The
+  CLI dev server serves the shell for any path, `sdocs build` emits an
+  `index.html` per route (deep links work on GitHub Pages with no rewrite
+  rules), and old `#/` bookmarks translate on load. Embedding keeps hash
+  URLs by default; the new `routing` config/prop switches either way, and
+  section-less links resolve into the default section.
+
+### Changed
+
+- **Config/prop rename: `title` + `logo`.** `title` is the header text
+  (was `logo`), `logo` the mascot image (was `icon`). Old configs with an
+  `icon` key are mapped automatically (with a console note); the `icon`
+  Explorer prop still works as an alias.
+
+## [0.0.60] - 2026-07-06
+
+### Added
+
+- **The page table of contents highlights the current section.** As the
+  page scrolls, the "On this page" entry for the section in view lights up;
+  clicking an entry highlights it immediately and holds it through the
+  smooth scroll.
+
 ## [0.0.59] - 2026-07-05
 
 ### Changed

package/dist/commands/build.js

@@ -1,9 +1,14 @@
 import { resolve } from 'node:path';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { build } from 'vite';
 import { svelte } from '@sveltejs/vite-plugin-svelte';
 import { loadConfig } from '../server/config.js';
 import { sdocsPlugin } from '../vite.js';
 import { generateBuildFiles, cleanBuildFiles } from '../server/app-gen.js';
+import { discoverDocFiles } from '../server/discovery.js';
+import { parseSdoc } from '../language/index.js';
+import { planEntitySnippets } from '../server/doc-model.js';
+import { buildSections } from '../explorer/tree-builder.js';
 import { svelteDedupe } from './dev.js';
 export async function buildCommand() {
     const cwd = process.cwd();
@@ -36,9 +41,52 @@ export async function buildCommand() {
                 },
             },
         });
+        // History routing: every route gets a physical index.html (a copy of the
+        // shell — asset URLs are root-absolute), so deep links work on any
+        // static host with no rewrite rules.
+        if ((config.routing ?? 'history') === 'history') {
+            const count = await emitRoutePages(config, cwd);
+            console.log(`[sdocs] Emitted ${count} route page(s)`);
+        }
         console.log(`[sdocs] Build complete → dist/`);
     }
     finally {
         await cleanBuildFiles(sdocsDir);
     }
 }
+/** Re-derive the route map from the doc files and copy the shell into each route. */
+async function emitRoutePages(config, cwd) {
+    const files = await discoverDocFiles(config.include, cwd);
+    const stubs = [];
+    for (const filePath of files) {
+        const doc = parseSdoc(await readFile(filePath, 'utf-8'));
+        for (const entity of doc.entities) {
+            stubs.push({
+                kind: entity.kind === 'DOCS' ? 'component' : entity.kind === 'PAGE' ? 'page' : 'layout',
+                filePath,
+                entitySlug: entity.slug,
+                meta: { title: entity.title },
+                previews: [],
+                examples: entity.kind === 'DOCS'
+                    ? planEntitySnippets(entity)
+                        .filter((s) => s.role === 'example')
+                        .map((s) => ({ name: s.name, slug: s.slug, role: s.role, body: '' }))
+                    : [],
+                content: null,
+            });
+        }
+    }
+    const map = buildSections(stubs, config.sidebar, {
+        defaultSection: config.defaultSection,
+        order: config.sections,
+    });
+    const shell = await readFile(resolve(cwd, 'dist/index.html'), 'utf-8');
+    let count = 0;
+    for (const key of map.routes.keys()) {
+        const dir = resolve(cwd, 'dist', key);
+        await mkdir(dir, { recursive: true });
+        await writeFile(resolve(dir, 'index.html'), shell);
+        count++;
+    }
+    return count;
+}

package/dist/commands/init.js

@@ -18,11 +18,14 @@ export default {
 	// Or named stylesheets:
 	// css: { light: './src/styles/light.css', dark: './src/styles/dark.css' },
 
-	// Sidebar logo text (default: 'sdocs')
+	// Header title text (default: 'sdocs')
+	// title: 'sdocs',
+
+	// Header logo: 'sdocs' for the mascot, an image URL, or false to hide (default: 'sdocs')
 	// logo: 'sdocs',
 
-	// Sidebar logo icon: 'sdocs' for the mascot, an image URL, or false to hide (default: 'sdocs')
-	// icon: 'sdocs',
+	// Top-bar section order — sections come from @Section/ title prefixes
+	// sections: ['Guides', 'Components'],
 
 	// Sidebar configuration
 	// sidebar: {

package/dist/explorer/Explorer.svelte

@@ -1,8 +1,9 @@
 <script lang="ts">
 	import type { DocEntry } from '../types.js';
-	import { initRouter, getPath } from './router.svelte.js';
-	import { buildTree, findDocByPath } from './tree-builder.js';
+	import { initRouter, getRoute, navigate, type RoutingMode } from './router.svelte.js';
+	import { buildSections, resolveRoute } from './tree-builder.js';
 	import Sidebar from './views/Sidebar.svelte';
+	import TopBar from './views/TopBar.svelte';
 	import ComponentView from './views/ComponentView.svelte';
 	import PageView from './views/PageView.svelte';
 	import LayoutView from './views/LayoutView.svelte';
@@ -14,7 +15,11 @@
 
 	interface Props {
 		docs: DocEntry[];
-		logo?: string;
+		/** Header title text */
+		title?: string;
+		/** Header logo: 'sdocs' for the built-in mascot, an image URL, or false to hide */
+		logo?: string | false;
+		/** @deprecated pre-0.0.61 name for `logo` */
 		icon?: string | false;
 		cssNames?: string[];
 		/** URL prefix for preview pages when the host app is served under a sub-path (e.g. SvelteKit's base). */
@@ -25,20 +30,43 @@
 			order?: Record<string, string[]>;
 			open?: string[];
 		};
+		/** Top-bar section order (unlisted sections follow alphabetically) */
+		sections?: string[];
+		/** Section for docs without an `@Section/` title prefix. Default: 'Docs' */
+		defaultSection?: string;
+		/** 'history' for real paths (server must fall back to the shell),
+		 * 'hash' for #/ URLs. Embedded default: 'hash'. */
+		routing?: RoutingMode;
+		/** Path prefix for history-mode routes (host app sub-path) */
+		basePath?: string;
 	}
 
 	let {
 		docs,
+		title,
 		logo = 'sdocs',
-		icon = 'sdocs',
+		icon,
 		cssNames = [],
 		previewBase = '',
 		pageModules = {},
-		sidebarConfig
+		sidebarConfig,
+		sections,
+		defaultSection = 'Docs',
+		routing = 'hash',
+		basePath = ''
 	}: Props = $props();
 
 	setContext('sdocs-preview-base', previewBase);
 
+	// Pre-0.0.61 props: `logo` was the header text and `icon` the image. An
+	// `icon` prop — or a logo value that can't be an asset path — is the old
+	// shape; map it onto the new semantics so embedded apps keep rendering.
+	const logoLooksLikeText = $derived(
+		typeof logo === 'string' && logo !== 'sdocs' && !/[./:]/.test(logo),
+	);
+	const headerTitle = $derived(title ?? (logoLooksLikeText ? (logo as string) : 'sdocs'));
+	const headerLogo = $derived(icon !== undefined ? icon : logoLooksLikeText ? 'sdocs' : logo);
+
 	let sidebarHidden = $state(false);
 	let activeStylesheet = $state<string | undefined>(undefined);
 	let theme = $state<ThemeMode>('light');
@@ -51,7 +79,7 @@
 	});
 
 	onMount(() => {
-		initRouter();
+		initRouter(routing, basePath);
 		const saved = localStorage.getItem('sdocs-theme') as ThemeMode | null;
 		if (saved && (saved === 'light' || saved === 'dark')) {
 			theme = saved;
@@ -66,43 +94,89 @@
 		localStorage.setItem('sdocs-theme', theme);
 	});
 
-	const currentPath = $derived(getPath());
-	const tree = $derived(buildTree(docs, sidebarConfig));
-	const resolved = $derived(findDocByPath(docs, currentPath));
+	const currentRoute = $derived(getRoute());
+	const sectionMap = $derived(
+		buildSections(docs, sidebarConfig, { defaultSection, order: sections }),
+	);
+	const showTopBar = $derived(sectionMap.sections.length > 1);
+	const activeSection = $derived(
+		(sectionMap.active
+			? sectionMap.sections.find((s) => s.slug === currentRoute[0])
+			: undefined) ??
+			sectionMap.sections.find((s) => s.isDefault) ??
+			sectionMap.sections[0],
+	);
+	const resolved = $derived(resolveRoute(sectionMap, currentRoute));
+
+	/** History mode: internal <a> clicks route client-side instead of reloading. */
+	function onLinkClick(e: MouseEvent) {
+		if (routing !== 'history') return;
+		if (e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey)
+			return;
+		const anchor = (e.target as Element | null)?.closest?.('a');
+		if (!anchor || anchor.target || anchor.hasAttribute('download')) return;
+		const href = anchor.getAttribute('href');
+		if (!href || href.startsWith('#')) return;
+		const url = new URL(anchor.href, location.href);
+		if (url.origin !== location.origin) return;
+		const base = basePath.replace(/\/$/, '');
+		if (base && !url.pathname.startsWith(base + '/')) return;
+		e.preventDefault();
+		navigate(url.pathname.slice(base.length).split('/').filter(Boolean).map(decodeURIComponent));
+	}
 </script>
 
-<div class="sdocs-app">
-	{#if !sidebarHidden}
-		<Sidebar
-			{tree}
-			{currentPath}
-			{logo}
-			{icon}
+<svelte:window onclick={onLinkClick} />
+
+<div class="sdocs-app" class:sdocs-app-with-topbar={showTopBar}>
+	{#if showTopBar}
+		<TopBar
+			title={headerTitle}
+			logo={headerLogo}
+			sections={sectionMap.sections}
+			activeSlug={activeSection?.slug}
 			{cssNames}
 			{activeStylesheet}
 			{theme}
-			onToggleFullscreen={() => sidebarHidden = true}
-			onStylesheetChange={(name) => activeStylesheet = name}
-			onThemeChange={(t) => theme = t}
+			onToggleFullscreen={() => (sidebarHidden = true)}
+			onStylesheetChange={(name) => (activeStylesheet = name)}
+			onThemeChange={(t) => (theme = t)}
 		/>
-	{:else}
-		<button class="sdocs-exit-fullscreen" onclick={() => sidebarHidden = false}>
-			&#9664; Exit fullscreen
-		</button>
 	{/if}
-	<main class="sdocs-main" class:sdocs-main-fullscreen={sidebarHidden}>
-		{#if resolved}
-			{#if resolved.doc.kind === 'page'}
-				<PageView doc={resolved.doc} {activeStylesheet} {pageModules} />
-			{:else if resolved.doc.kind === 'layout'}
-				<LayoutView doc={resolved.doc} {activeStylesheet} />
-			{:else}
-				<ComponentView doc={resolved.doc} snippetName={resolved.snippetName} {activeStylesheet} />
-			{/if}
+	<div class="sdocs-body">
+		{#if !sidebarHidden}
+			<Sidebar
+				tree={activeSection?.tree ?? []}
+				{currentRoute}
+				title={headerTitle}
+				logo={headerLogo}
+				showHeader={!showTopBar}
+				cssNames={showTopBar ? [] : cssNames}
+				{activeStylesheet}
+				{theme}
+				onToggleFullscreen={() => (sidebarHidden = true)}
+				onStylesheetChange={(name) => (activeStylesheet = name)}
+				onThemeChange={(t) => (theme = t)}
+			/>
 		{:else}
-			<HomePage {docs} {logo} />
+			<button class="sdocs-exit-fullscreen" onclick={() => (sidebarHidden = false)}>
+				&#9664; Exit fullscreen
+			</button>
 		{/if}
-	</main>
+		<main class="sdocs-main" class:sdocs-main-fullscreen={sidebarHidden}>
+			{#if resolved}
+				{#if resolved.doc.kind === 'page'}
+					<PageView doc={resolved.doc} {activeStylesheet} {pageModules} />
+				{:else if resolved.doc.kind === 'layout'}
+					<LayoutView doc={resolved.doc} {activeStylesheet} />
+				{:else}
+					<ComponentView doc={resolved.doc} snippetName={resolved.snippetName} {activeStylesheet} />
+				{/if}
+			{:else}
+				<HomePage {docs} title={headerTitle} logo={headerLogo} />
+			{/if}
+		</main>
+	</div>
 </div>
 
 <style>
@@ -110,10 +184,16 @@
 		margin: 0;
 		padding: 0;
 		display: flex;
+		flex-direction: column;
 		height: 100vh;
 		overflow: hidden;
 		position: relative;
 	}
+	.sdocs-body {
+		display: flex;
+		flex: 1;
+		min-height: 0;
+	}
 	.sdocs-main {
 		flex: 1;
 		overflow-y: auto;

package/dist/explorer/router.svelte.d.ts

@@ -1,11 +1,23 @@
-/** Hash-based router for sdocs. Uses #/Segment/Segment/... format. */
-/** Get the current path segments */
-export declare function getPath(): string[];
-/** Navigate to a path */
-export declare function navigate(segments: string[]): void;
-/** Initialize the router — call once on app startup */
-export declare function initRouter(): void;
-/** Build a title path from meta.title (e.g. 'Demo / Button' → ['Demo', 'Button']) */
-export declare function titleToPath(title: string): string[];
-/** Build a hash string from a title path (for href attributes) */
-export declare function pathToHash(segments: string[]): string;
+/**
+ * Router for the Explorer. Two modes over the same slug-segment routes:
+ * - 'history': real paths (/guides/installation). The standalone CLI default —
+ *   its dev server and static build guarantee every path serves the shell.
+ * - 'hash': #/guides/installation. The embedded default — works under any
+ *   host routing without server cooperation.
+ */
+export type RoutingMode = 'history' | 'hash';
+/** Get the current route segments */
+export declare function getRoute(): string[];
+/** Navigate to a route (segments are slugs) */
+export declare function navigate(segments: string[], opts?: {
+    replace?: boolean;
+}): void;
+/** Href string for a route, in the active mode (for <a href>) */
+export declare function routeHref(segments: string[]): string;
+/**
+ * Initialize the router — call once on app startup.
+ * In history mode a leftover `#/…` URL (a pre-history bookmark) is translated
+ * in place: its segments were display names with spaces as hyphens, which
+ * lowercased are today's slugs for almost every title.
+ */
+export declare function initRouter(routingMode: RoutingMode, basePath?: string): void;

package/dist/explorer/router.svelte.js

@@ -1,45 +1,75 @@
-/** Hash-based router for sdocs. Uses #/Segment/Segment/... format. */
-/** Current hash path segments (reactive) */
-let currentPath = $state([]);
-/** Get the current path segments */
-export function getPath() {
-    return currentPath;
+/**
+ * Router for the Explorer. Two modes over the same slug-segment routes:
+ * - 'history': real paths (/guides/installation). The standalone CLI default —
+ *   its dev server and static build guarantee every path serves the shell.
+ * - 'hash': #/guides/installation. The embedded default — works under any
+ *   host routing without server cooperation.
+ */
+// Reactive: initRouter runs on mount, after hrefs were first rendered — they
+// recompute when the mode lands.
+let mode = $state('hash');
+let base = $state('');
+/** Current route segments (reactive) */
+let currentRoute = $state([]);
+/** Get the current route segments */
+export function getRoute() {
+    return currentRoute;
 }
-/** Navigate to a path */
-export function navigate(segments) {
-    const hash = segments.length > 0
-        ? '#/' + segments.map(encodeSegment).join('/')
-        : '#/';
-    window.location.hash = hash;
+/** Navigate to a route (segments are slugs) */
+export function navigate(segments, opts) {
+    const url = routeHref(segments);
+    if (mode === 'history') {
+        if (opts?.replace)
+            history.replaceState(null, '', url);
+        else
+            history.pushState(null, '', url);
+        currentRoute = segments;
+    }
+    else {
+        if (opts?.replace)
+            location.replace(url);
+        else
+            location.hash = url;
+        // hashchange fires and re-parses; set eagerly for same-hash calls
+        currentRoute = segments;
+    }
 }
-/** Parse hash into path segments */
-function parseHash() {
-    const hash = window.location.hash;
-    if (!hash || hash === '#' || hash === '#/')
-        return [];
-    const path = hash.startsWith('#/') ? hash.slice(2) : hash.slice(1);
-    return path.split('/').filter(Boolean).map(decodeSegment);
+/** Href string for a route, in the active mode (for <a href>) */
+export function routeHref(segments) {
+    const path = segments.map(encodeURIComponent).join('/');
+    return mode === 'history' ? `${base}/${path}` : `#/${path}`;
 }
-/** Encode a segment: spaces → hyphens */
-function encodeSegment(s) {
-    return s.replace(/\s+/g, '-');
+function parseLocation() {
+    const raw = mode === 'history'
+        ? location.pathname.startsWith(base)
+            ? location.pathname.slice(base.length)
+            : location.pathname
+        : location.hash.replace(/^#/, '');
+    return raw.split('/').filter(Boolean).map(decodeURIComponent);
 }
-/** Decode a segment: hyphens → spaces */
-function decodeSegment(s) {
-    return s.replace(/-/g, ' ');
-}
-/** Initialize the router — call once on app startup */
-export function initRouter() {
-    currentPath = parseHash();
-    window.addEventListener('hashchange', () => {
-        currentPath = parseHash();
-    });
-}
-/** Build a title path from meta.title (e.g. 'Demo / Button' → ['Demo', 'Button']) */
-export function titleToPath(title) {
-    return title.split('/').map((s) => s.trim()).filter(Boolean);
-}
-/** Build a hash string from a title path (for href attributes) */
-export function pathToHash(segments) {
-    return '#/' + segments.map(encodeSegment).join('/');
+/**
+ * Initialize the router — call once on app startup.
+ * In history mode a leftover `#/…` URL (a pre-history bookmark) is translated
+ * in place: its segments were display names with spaces as hyphens, which
+ * lowercased are today's slugs for almost every title.
+ */
+export function initRouter(routingMode, basePath = '') {
+    mode = routingMode;
+    base = basePath.replace(/\/$/, '');
+    if (mode === 'history' && location.hash.startsWith('#/')) {
+        const legacy = location.hash
+            .slice(2)
+            .split('/')
+            .filter(Boolean)
+            .map((s) => decodeURIComponent(s).toLowerCase());
+        history.replaceState(null, '', `${base}/${legacy.join('/')}`);
+    }
+    currentRoute = parseLocation();
+    const onChange = () => {
+        currentRoute = parseLocation();
+    };
+    if (mode === 'history')
+        window.addEventListener('popstate', onChange);
+    else
+        window.addEventListener('hashchange', onChange);
 }

package/dist/explorer/tree-builder.d.ts

@@ -3,12 +3,16 @@ export type TreeNodeType = 'folder' | 'group' | 'component' | 'page' | 'layout';
 export interface TreeNode {
     name: string;
     type: TreeNodeType;
-    /** Full path segments from root (for routing) */
+    /** Display path segments from the section root */
     path: string[];
+    /** URL route segments from the site root (slugified, section included) */
+    route: string[];
     /** Children nodes */
     children: TreeNode[];
     /** The doc entry (only for component/page/layout nodes) */
     doc?: DocEntry;
+    /** Set on example child nodes: the example this node opens */
+    snippetName?: string;
     /** Example titles for component nodes (sidebar sub-pages) */
     examples?: string[];
     /** Whether this node should be expanded by default */
@@ -18,19 +22,55 @@ interface SidebarConfig {
     order?: Record<string, string[]>;
     open?: string[];
 }
-/** Build a tree from flat doc entries */
-export declare function buildTree(docs: DocEntry[], sidebar?: SidebarConfig): TreeNode[];
+/** One top-bar section: a name and its own sidebar tree */
+export interface SectionTree {
+    name: string;
+    slug: string;
+    isDefault: boolean;
+    tree: TreeNode[];
+    /** Route of the section's first document (top-bar tab target) */
+    firstRoute: string[] | null;
+}
+/** What a URL route resolves to */
+export interface RouteTarget {
+    doc: DocEntry;
+    snippetName?: string;
+}
+/** Everything the Explorer needs to render sections and resolve URLs */
+export interface SectionMap {
+    sections: SectionTree[];
+    routes: Map<string, RouteTarget>;
+    /** True once any doc declares an `@Section` — routes carry the section slug */
+    active: boolean;
+}
+/** Slug for one route segment — same rules as page heading anchors. */
+export declare function slugifySegment(text: string): string;
+/** Split an optional `@Section` first segment off a title. */
+export declare function splitSection(title: string | null | undefined): {
+    section: string | null;
+    rest: string;
+};
 /**
- * The title shown to users. A leading ':' on the first segment is a sidebar
- * grouping directive (see buildTree), not part of the displayed title, so it
- * is stripped for headings.
+ * Group docs into sections (from `@Section/` title prefixes, the rest into the
+ * default section), build each section's tree, and register every navigable
+ * route. Section order: the config list first, unlisted after (default
+ * section first, then alphabetical).
+ */
+export declare function buildSections(docs: DocEntry[], sidebar?: SidebarConfig, opts?: {
+    defaultSection?: string;
+    order?: string[];
+}): SectionMap;
+/**
+ * Resolve URL segments to a doc. Links that omit the section — bookmarks from
+ * before sections existed — fall back into the default section.
+ */
+export declare function resolveRoute(map: SectionMap, segments: string[]): RouteTarget | null;
+/** Build a tree from flat doc entries; routes get `routePrefix` prepended. */
+export declare function buildTree(docs: DocEntry[], sidebar?: SidebarConfig, routePrefix?: string[]): TreeNode[];
+/**
+ * The title shown to users. The `@Section/` prefix routes to a top-bar
+ * section and a leading ':' on the first segment is a sidebar grouping
+ * directive (see buildTree) — neither is part of the displayed title.
  */
 export declare function displayTitle(title: string | null | undefined): string;
-/** Check if a path matches a tree node (for active state) */
-export declare function pathMatchesNode(currentPath: string[], node: TreeNode): boolean;
-/** Find the doc entry for a given path */
-export declare function findDocByPath(docs: DocEntry[], path: string[]): {
-    doc: DocEntry;
-    snippetName?: string;
-} | null;
 export {};