sdocs 0.0.56 → 0.0.58

package/CHANGELOG.md

@@ -7,6 +7,64 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.58] - 2026-07-05
+
+### Added
+
+- **Richer page markdown.** GitHub-style alerts (`> [!NOTE]`, `[!TIP]`,
+  `[!IMPORTANT]`, `[!WARNING]`, `[!CAUTION]`) render as tinted callouts;
+  task lists get proper checkboxes; table columns honor `:---:` alignment;
+  external links open in a new tab (internal ones stay in the app); images
+  render lazily and Svelte-safe.
+- **`static` config option.** A folder of static assets served at the site
+  root in dev and copied into `dist/` by `sdocs build` — `![hero](/hero.png)`
+  in a page just works. Powers the standalone CLI flows; embedded apps keep
+  using the host's public directory.
+- **Page column alignment.** `content.page.contentX` (config) and
+  `contentX` on `[PAGE]` align the content column `left`/`center`/`right`.
+- **A body `#` heading takes over as the page title** — the header no longer
+  duplicates it; the entity `title` keeps naming the sidebar entry.
+
+### Changed
+
+- **A page's `maxWidth` now bounds the content column together with its
+  table of contents**; when the toc is hidden the prose takes its space.
+
+### Fixed
+
+- **Code fences can show component tags.** A `<Component />` line inside a
+  markdown fence, preceded by a blank line, was treated as a live Svelte
+  island and rendered (or crashed the page) instead of staying highlighted
+  code. Fences now shield island detection, matching the scanner and the
+  editor projection.
+
+## [0.0.57] - 2026-07-05
+
+### Added
+
+- **`[example]` blocks inside `[PAGE]`.** Pages can now stage real code in
+  the project's context, mid-prose: an example renders in place on an
+  isolated iframe stage that loads the configured `css`, with a collapsed
+  code panel — exactly like an example in `[DOCS]`. Stage attributes
+  (`maxWidth`, `padding`, `direction`, `gap`, `contentX`, `contentY`)
+  cascade from `content.docs`. Titles are required and unique per page;
+  markdown fences shield block syntax, so a fence may show `[example]`
+  without escaping.
+
+### Changed
+
+- **Page prose renders natively in the Explorer**, with the docs app's own
+  typography — no longer inside an iframe that loads the project `css`. The
+  boundary is now crisp: documentation is docs-styled, stages are
+  project-styled. Pages gain real markdown styling (headings, lists, tables,
+  code), direct table-of-contents scrolling, and native text flow. Svelte
+  islands still work and run in the docs context — showcase code belongs in
+  `[example]` blocks.
+- **Embedded hosts pass `pageModules`.** `virtual:sdocs` now exports
+  `pageModules`; forward it to `<Explorer {docs} {cssNames} {pageModules}>`
+  so pages render their content. Hosts that don't pass it show page examples
+  and headers but no body.
+
 ## [0.0.56] - 2026-07-05
 
 ### Added

package/dist/commands/build.js

@@ -19,6 +19,8 @@ export async function buildCommand() {
         await build({
             configFile: false,
             root: sdocsDir,
+            // The project's static assets (config `static`), copied into dist/
+            publicDir: config.static ?? false,
             resolve: {
                 dedupe: svelteDedupe(cwd),
             },

package/dist/commands/dev.js

@@ -37,6 +37,8 @@ export async function devCommand() {
     const server = await createServer({
         configFile: false,
         root: sdocsDir,
+        // The project's static assets (config `static`), served at the site root
+        publicDir: config.static ?? false,
         resolve: {
             dedupe: svelteDedupe(cwd),
         },

package/dist/explorer/Explorer.svelte

@@ -19,6 +19,8 @@
 		cssNames?: string[];
 		/** URL prefix for preview pages when the host app is served under a sub-path (e.g. SvelteKit's base). */
 		previewBase?: string;
+		/** Native page components from `virtual:sdocs`, keyed by contentKey. */
+		pageModules?: Record<string, () => Promise<{ default: unknown }>>;
 		sidebarConfig?: {
 			order?: Record<string, string[]>;
 			open?: string[];
@@ -31,6 +33,7 @@
 		icon = 'sdocs',
 		cssNames = [],
 		previewBase = '',
+		pageModules = {},
 		sidebarConfig
 	}: Props = $props();
 
@@ -90,7 +93,7 @@
 	<main class="sdocs-main" class:sdocs-main-fullscreen={sidebarHidden}>
 		{#if resolved}
 			{#if resolved.doc.kind === 'page'}
-				<PageView doc={resolved.doc} {activeStylesheet} />
+				<PageView doc={resolved.doc} {activeStylesheet} {pageModules} />
 			{:else if resolved.doc.kind === 'layout'}
 				<LayoutView doc={resolved.doc} {activeStylesheet} />
 			{:else}

package/dist/explorer/views/PageView.svelte

@@ -1,73 +1,129 @@
 <script lang="ts">
+	import type { Component } from 'svelte';
 	import type { DocEntry } from '../../types.js';
+	import { Icon } from '../../ui/Icon/index.js';
+	import CollapsiblePanel from './CollapsiblePanel.svelte';
 	import PreviewFrame from './PreviewFrame.svelte';
 	import { displayTitle } from '../tree-builder.js';
 
 	interface Props {
 		doc: DocEntry;
 		activeStylesheet?: string;
+		/** Native page components from `virtual:sdocs`, keyed by contentKey. */
+		pageModules?: Record<string, () => Promise<{ default: unknown }>>;
 	}
 
-	let { doc, activeStylesheet }: Props = $props();
+	let { doc, activeStylesheet, pageModules = {} }: Props = $props();
 
 	const meta = $derived(doc.meta);
-	const contentSnippet = $derived(doc.content);
 	const toc = $derived(doc.toc ?? []);
 
+	// The page body compiles to its own component (prose + islands + example
+	// markers); it renders here, natively — sdocs styling, no iframe. Only the
+	// [example] stages load the project's css, each in its own PreviewFrame.
+	let PageComponent = $state<Component | null>(null);
+	let container: HTMLElement | undefined = $state();
+
+	$effect(() => {
+		const load = doc.contentKey ? pageModules[doc.contentKey] : undefined;
+		PageComponent = null;
+		if (!load) return;
+		let stale = false;
+		load().then((mod) => {
+			if (!stale) PageComponent = mod.default as Component;
+		});
+		return () => {
+			stale = true;
+		};
+	});
+
 	function scrollToHeading(id: string) {
-		const iframe = document.querySelector('.sdocs-page-content .sdocs-iframe') as HTMLIFrameElement;
-		if (iframe?.contentWindow) {
-			iframe.contentWindow.postMessage({ type: 'sdocs:scroll-to', id }, '*');
-		}
+		container?.querySelector(`#${CSS.escape(id)}`)?.scrollIntoView({ behavior: 'smooth' });
 	}
+
+	// contentX aligns the whole column (content + toc) inside the view.
+	const columnMargin = $derived(
+		doc.contentX === 'center' ? '0 auto' : doc.contentX === 'right' ? '0 0 0 auto' : undefined,
+	);
 </script>
 
-<div class="sdocs-page-view">
-	<div class="sdocs-page-main" style:max-width={doc.maxWidth}>
-		<!-- Header -->
-		<div class="sdocs-view-header">
-			<h1 class="sdocs-view-title">{displayTitle(meta.title)}</h1>
-			{#if meta.description}
-				<p class="sdocs-view-description">{meta.description}</p>
+{#snippet exampleFrame(index: number)}
+	{@const example = doc.examples?.[index]}
+	{#if example}
+		<div class="sdocs-page-example">
+			{#if example.name}
+				<h3 class="sdocs-example-title">
+					<Icon name="bookmark" --w="14px" --h="14px" --fill="var(--color-example-500)" />
+					{example.name}
+				</h3>
 			{/if}
+			<div class="sdocs-panels">
+				<div class="sdocs-preview-wrapper">
+					<PreviewFrame src={example.previewUrl ?? ''} {activeStylesheet} />
+				</div>
+				<CollapsiblePanel title="Code" defaultExpanded={false}>
+					<div class="sdocs-code-block">{@html example.highlightedHtml ?? ''}</div>
+				</CollapsiblePanel>
+			</div>
 		</div>
+	{/if}
+{/snippet}
 
-		<!-- Content -->
-		{#if contentSnippet}
-			<div class="sdocs-page-content">
-				<PreviewFrame src={contentSnippet.previewUrl} {activeStylesheet} />
+<div class="sdocs-page-view" style:padding={doc.padding}>
+	<!-- maxWidth constrains the whole column — content plus toc; contentX
+	     places it. Without a toc the content takes the toc's space. -->
+	<div class="sdocs-page-inner" style:max-width={doc.maxWidth} style:margin={columnMargin}>
+		<div class="sdocs-page-main">
+			<!-- Header: a body `#` heading takes over as the page title -->
+			{#if !doc.bodyTitle}
+				<div class="sdocs-view-header">
+					<h1 class="sdocs-view-title">{displayTitle(meta.title)}</h1>
+					{#if meta.description}
+						<p class="sdocs-view-description">{meta.description}</p>
+					{/if}
+				</div>
+			{/if}
+
+			<!-- Content -->
+			<div class="sdocs-page-content" bind:this={container}>
+				{#if PageComponent}
+					<PageComponent __sdocsExample={exampleFrame} />
+				{/if}
 			</div>
+		</div>
+
+		<!-- Table of Contents -->
+		{#if toc.length > 0 && doc.showToc !== false}
+			<aside class="sdocs-toc">
+				<h3 class="sdocs-toc-title">On this page</h3>
+				<nav>
+					<ul class="sdocs-toc-list">
+						{#each toc as heading (heading.id)}
+							<li class="sdocs-toc-item" style:padding-left="{(heading.level - 2) * 12}px">
+								<button
+									class="sdocs-toc-link"
+									onclick={() => scrollToHeading(heading.id)}
+								>
+									{heading.text}
+								</button>
+							</li>
+						{/each}
+					</ul>
+				</nav>
+			</aside>
 		{/if}
 	</div>
-
-	<!-- Table of Contents -->
-	{#if toc.length > 0 && doc.showToc !== false}
-		<aside class="sdocs-toc">
-			<h3 class="sdocs-toc-title">On this page</h3>
-			<nav>
-				<ul class="sdocs-toc-list">
-					{#each toc as heading (heading.id)}
-						<li class="sdocs-toc-item" style:padding-left="{(heading.level - 2) * 12}px">
-							<button
-								class="sdocs-toc-link"
-								onclick={() => scrollToHeading(heading.id)}
-							>
-								{heading.text}
-							</button>
-						</li>
-					{/each}
-				</ul>
-			</nav>
-		</aside>
-	{/if}
 </div>
 
 <style>
 	.sdocs-page-view {
+		/* padding comes from the doc entry (config/entity cascade) */
+		font-family: var(--sans);
+	}
+	.sdocs-page-inner {
 		display: flex;
 		gap: 24px;
-		padding: 24px 32px;
-		font-family: var(--sans);
+		/* max-width and margin (contentX) come from the doc entry */
 	}
 	.sdocs-page-main {
 		flex: 1;
@@ -87,9 +143,197 @@
 		color: var(--color-base-500);
 		margin: 6px 0 0;
 	}
+
+	/* ── Page prose: the docs app's own typography ── */
 	.sdocs-page-content {
-		flex: 1;
+		font-size: 14px;
+		line-height: 1.7;
+		color: var(--color-base-800);
+	}
+	.sdocs-page-content :global(h1),
+	.sdocs-page-content :global(h2),
+	.sdocs-page-content :global(h3),
+	.sdocs-page-content :global(h4),
+	.sdocs-page-content :global(h5),
+	.sdocs-page-content :global(h6) {
+		color: var(--color-base-900);
+		font-weight: 650;
+		line-height: 1.3;
+		margin: 1.6em 0 0.5em;
+		scroll-margin-top: 16px;
+	}
+	.sdocs-page-content :global(h1) { font-size: 22px; }
+	.sdocs-page-content :global(h2) { font-size: 18px; }
+	.sdocs-page-content :global(h3) { font-size: 15px; }
+	.sdocs-page-content :global(h4),
+	.sdocs-page-content :global(h5),
+	.sdocs-page-content :global(h6) { font-size: 14px; }
+	.sdocs-page-content :global(h1:first-child),
+	.sdocs-page-content :global(h2:first-child),
+	.sdocs-page-content :global(h3:first-child) {
+		margin-top: 0;
+	}
+	.sdocs-page-content :global(p) {
+		margin: 0.7em 0;
+	}
+	.sdocs-page-content :global(a) {
+		color: var(--color-action-500, var(--color-base-900));
+		text-decoration: underline;
+		text-underline-offset: 2px;
+	}
+	.sdocs-page-content :global(ul),
+	.sdocs-page-content :global(ol) {
+		margin: 0.7em 0;
+		padding-left: 1.6em;
+	}
+	.sdocs-page-content :global(li) {
+		margin: 0.25em 0;
+	}
+	.sdocs-page-content :global(blockquote) {
+		margin: 0.9em 0;
+		padding: 2px 16px;
+		border-left: 3px solid var(--color-base-200);
+		color: var(--color-base-600);
+	}
+	.sdocs-page-content :global(hr) {
+		border: none;
+		border-top: 1px solid var(--color-base-200);
+		margin: 24px 0;
+	}
+	.sdocs-page-content :global(code) {
+		font-family: var(--mono);
+		font-size: 0.92em;
+	}
+	.sdocs-page-content :global(:not(pre) > code) {
+		background: var(--color-base-100);
+		border-radius: 4px;
+		padding: 1px 5px;
+	}
+	.sdocs-page-content :global(pre) {
+		margin: 0.9em 0;
+		padding: 12px;
+		border-radius: 6px;
+		overflow-x: auto;
+		font-size: 13px;
+		line-height: 1.5;
+		tab-size: 4;
+	}
+	.sdocs-page-content :global(table) {
+		border-collapse: collapse;
+		margin: 0.9em 0;
+		display: block;
+		max-width: 100%;
+		overflow-x: auto;
+	}
+	.sdocs-page-content :global(th),
+	.sdocs-page-content :global(td) {
+		border: 1px solid var(--color-base-200);
+		padding: 6px 12px;
+		text-align: left;
 	}
+	.sdocs-page-content :global(td[align='center']),
+	.sdocs-page-content :global(th[align='center']) {
+		text-align: center;
+	}
+	.sdocs-page-content :global(td[align='right']),
+	.sdocs-page-content :global(th[align='right']) {
+		text-align: right;
+	}
+	.sdocs-page-content :global(th) {
+		background: var(--color-base-50);
+		font-weight: 600;
+	}
+	.sdocs-page-content :global(img) {
+		max-width: 100%;
+		border-radius: 6px;
+	}
+
+	/* Task lists: GitHub-style checkboxes, no bullet */
+	.sdocs-page-content :global(li:has(> input[type='checkbox']:first-child)) {
+		list-style: none;
+		margin-left: -1.3em;
+	}
+	.sdocs-page-content :global(li > input[type='checkbox']) {
+		margin-right: 6px;
+		vertical-align: -2px;
+	}
+
+	/* GitHub-style alerts: > [!NOTE] / [!TIP] / [!IMPORTANT] / [!WARNING] / [!CAUTION] */
+	.sdocs-page-content :global(.sdocs-alert) {
+		margin: 0.9em 0;
+		padding: 8px 16px;
+		border-left: 3px solid var(--sdocs-alert-color);
+		border-radius: 0 6px 6px 0;
+		background: color-mix(in srgb, var(--sdocs-alert-color) 6%, transparent);
+	}
+	.sdocs-page-content :global(.sdocs-alert-label) {
+		font-size: 13px;
+		font-weight: 650;
+		color: var(--sdocs-alert-color);
+		margin: 0.25em 0 0;
+	}
+	.sdocs-page-content :global(.sdocs-alert-note) {
+		--sdocs-alert-color: var(--color-blue-500);
+	}
+	.sdocs-page-content :global(.sdocs-alert-tip) {
+		--sdocs-alert-color: var(--color-green-500);
+	}
+	.sdocs-page-content :global(.sdocs-alert-important) {
+		--sdocs-alert-color: var(--color-purple-500);
+	}
+	.sdocs-page-content :global(.sdocs-alert-warning) {
+		--sdocs-alert-color: var(--color-amber-500);
+	}
+	.sdocs-page-content :global(.sdocs-alert-caution) {
+		--sdocs-alert-color: var(--color-red-500);
+	}
+
+	/* ── Example stages in the page flow ── */
+	.sdocs-page-example {
+		display: flex;
+		flex-direction: column;
+		gap: 8px;
+		margin: 16px 0;
+	}
+	.sdocs-example-title {
+		display: flex;
+		align-items: center;
+		gap: 6px;
+		font-size: 15px;
+		font-weight: 600;
+		color: var(--color-base-800);
+		margin: 0;
+	}
+	.sdocs-panels {
+		display: flex;
+		flex-direction: column;
+		gap: 1px;
+		border: 1px solid var(--color-base-200);
+		background: var(--color-base-200);
+		border-radius: 8px;
+		overflow: hidden;
+	}
+	.sdocs-preview-wrapper {
+		/* stage padding lives inside the iframe (config/block cascade) */
+		background: var(--color-base-0);
+	}
+	.sdocs-code-block {
+		overflow-x: auto;
+		font-size: 13px;
+		line-height: 1.5;
+		tab-size: 4;
+	}
+	.sdocs-code-block :global(pre) {
+		margin: 0;
+		padding: 12px;
+		border-radius: 6px;
+		overflow-x: auto;
+	}
+	.sdocs-code-block :global(code) {
+		font-family: var(--mono);
+	}
+
+	/* ── Table of contents ── */
 	.sdocs-toc {
 		width: 200px;
 		flex-shrink: 0;

package/dist/grammar/sdoc.tmLanguage.json

@@ -244,6 +244,9 @@
 					"while": "(^|\\G)(?!\\s*\\[/PAGE\\]\\s*$)(?:\\t|[ ]{1,4})?",
 					"contentName": "meta.embedded.block.markdown",
 					"patterns": [
+						{
+							"include": "#page-example"
+						},
 						{
 							"include": "#page-svelte-block"
 						},
@@ -570,6 +573,48 @@
 					"include": "source.ts"
 				}
 			]
+		},
+		"page-example": {
+			"name": "meta.block.example.sdoc",
+			"begin": "(^|\\G)\\s*(\\[)(example)\\b(.*)$",
+			"beginCaptures": {
+				"2": {
+					"name": "punctuation.definition.tag.begin.sdoc"
+				},
+				"3": {
+					"name": "entity.name.tag.sdoc"
+				},
+				"4": {
+					"patterns": [
+						{
+							"include": "#attributes"
+						}
+					]
+				}
+			},
+			"end": "(^|\\G)\\s*(\\[/)(example)(\\])\\s*$",
+			"endCaptures": {
+				"2": {
+					"name": "punctuation.definition.tag.begin.sdoc"
+				},
+				"3": {
+					"name": "entity.name.tag.sdoc"
+				},
+				"4": {
+					"name": "punctuation.definition.tag.end.sdoc"
+				}
+			},
+			"patterns": [
+				{
+					"begin": "(^|\\G)",
+					"while": "(^|\\G)(?!\\s*\\[/example\\]\\s*$)",
+					"patterns": [
+						{
+							"include": "source.svelte"
+						}
+					]
+				}
+			]
 		}
 	}
 }

package/dist/language/config-schema.js

@@ -65,6 +65,11 @@ export const configSchema = {
         doc: 'CSS loaded inside preview iframes — a single stylesheet path, or a map of named stylesheets to switch between.',
         insert: ": '$0'",
     },
+    static: {
+        detail: 'string',
+        doc: 'Folder of static assets served at the site root — images for pages, files for previews. Standalone CLI flows; embedded apps use the host\'s public directory.',
+        insert: ": './${0:static}'",
+    },
     logo: {
         detail: 'string',
         doc: 'Sidebar logo text. Default: `sdocs`.',
@@ -101,7 +106,7 @@ export const configSchema = {
         object: {
             page: {
                 detail: 'object',
-                doc: '`[PAGE]` content. Defaults: `maxWidth` `1200px`, `padding` `32px`, `toc` `true`.',
+                doc: '`[PAGE]` content. Defaults: `maxWidth` `1200px`, `padding` `32px`, `toc` `true`, `contentX` `left`.',
                 insert: ': {\n\t$0\n}',
                 object: {
                     maxWidth,
@@ -112,6 +117,13 @@ export const configSchema = {
                         insert: ': ${0:true}',
                         values: ['true', 'false'],
                     },
+                    contentX: {
+                        detail: "'left' | 'center' | 'right'",
+                        doc: 'Horizontal alignment of the page content column (with its toc). Default: `left`.',
+                        insert: ": '${0:center}'",
+                        values: ['left', 'center', 'right'],
+                        quoted: true,
+                    },
                 },
             },
             docs: {

package/dist/language/page-islands.d.ts

@@ -19,5 +19,7 @@ export interface PageSegment {
     /** Verbatim lines of the segment */
     lines: string[];
 }
-/** Split a page body into prose and island segments. */
+/** Split a page body into prose and island segments. Lines inside markdown
+ * code fences are always prose — a component tag shown in a fence must stay
+ * displayed code, never a live island. */
 export declare function segmentPageBody(body: string): PageSegment[];

package/dist/language/page-islands.js

@@ -80,7 +80,9 @@ function lineDepths(line) {
     }
     return { svelte, html };
 }
-/** Split a page body into prose and island segments. */
+/** Split a page body into prose and island segments. Lines inside markdown
+ * code fences are always prose — a component tag shown in a fence must stay
+ * displayed code, never a live island. */
 export function segmentPageBody(body) {
     const lines = body.split('\n');
     const segments = [];
@@ -92,9 +94,21 @@ export function segmentPageBody(body) {
         }
         current.lines.push(line);
     };
+    let inFence = false;
     let i = 0;
     while (i < lines.length) {
         const line = lines[i];
+        if (/^\s*(`{3,}|~{3,})/.test(line)) {
+            inFence = !inFence;
+            push('prose', line);
+            i++;
+            continue;
+        }
+        if (inFence) {
+            push('prose', line);
+            i++;
+            continue;
+        }
         const prevBlank = i === 0 || lines[i - 1].trim() === '';
         if (prevBlank && line.trim() !== '' && startsIsland(line)) {
             // Consume the island: until Svelte blocks and HTML tags balance out.

package/dist/language/parser.d.ts

@@ -59,7 +59,11 @@ export interface PageEntity {
     title: string;
     slug: string;
     sizing: Sizing;
+    /** Prose body with each [example] block replaced by a
+     * `{@render __sdocsExample?.(i)}` marker the page renderer resolves. */
     body: string;
+    /** The page's [example] blocks, in marker order */
+    examples: ExampleBlock[];
     bodySpan: Span;
     openerSpan: Span;
     span: Span;