sdocs 0.0.51 → 0.0.53

package/CHANGELOG.md

@@ -7,6 +7,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.53] - 2026-07-05
+
+### Added
+
+- **Content layout is configurable — globally and in place.** The config's
+  `content` option sets per-kind defaults, and the same names work as entity
+  and block attributes (block beats entity beats config):
+  - `maxWidth` — the content column for `[DOCS]`/`[PAGE]` (default `1200px`),
+    the stage for `[LAYOUT]` (default `100%`) and for `[preview]`/`[example]`
+    (default `100%`; narrower stages center).
+  - `padding` — page content `32px`, preview/example stages `16px`
+    (settable on `[DOCS]` as the entity default), layout stages `0px`.
+  - `direction` / `gap` — preview/example stages are flex containers:
+    `flex-direction` (default `row`) and `gap` (default `16px`).
+  - `toc` — `[PAGE]` table-of-contents visibility (default `true`;
+    `toc="false"` hides it).
+
+## [0.0.52] - 2026-07-05
+
+### Added
+
+- **Svelte islands in `[PAGE]` bodies.** A line opening a component/HTML tag
+  or a Svelte block (`{#snippet`, `{@render`) after a blank line starts an
+  island that passes to Svelte verbatim, until its tags and blocks balance —
+  blank lines inside are fine. Markdown can no longer split a snippet across
+  paragraphs or cut an HTML section in half. Snippets declared anywhere on
+  the page are renderable from anywhere (they land at the top level of the
+  compiled fragment), so one `{#snippet}` can serve many sections.
+- **Svelte coloring inside page bodies.** `{#…}…{/…}` blocks highlight as
+  Svelte throughout — keywords, typed params, and the markup inside them —
+  and `{@…}` tags color as keywords with TypeScript interiors, instead of
+  HTML-guess colors. Fenced code and inline code stay inert.
+
 ## [0.0.51] - 2026-07-05
 
 ### Changed

package/dist/explorer/views/ComponentView.svelte

@@ -288,7 +288,7 @@
 	);
 </script>
 
-<div class="sdocs-component-view">
+<div class="sdocs-component-view" style:max-width={doc.maxWidth}>
 	{#if focusedSnippet}
 		<!-- Example full-page view -->
 		<div class="sdocs-view-header">
@@ -482,7 +482,7 @@
 <style>
 	.sdocs-component-view {
 		padding: 24px 32px;
-		max-width: 1120px;
+		/* max-width comes from the doc entry (config/entity cascade) */
 		font-family: var(--sans);
 	}
 	.sdocs-doc-section {
@@ -579,8 +579,8 @@
 		overflow: hidden;
 	}
 	.sdocs-preview-wrapper {
+		/* stage padding lives inside the iframe (config/entity/block cascade) */
 		background: var(--color-base-0);
-		padding: 16px;
 	}
 	.sdocs-divider {
 		border: none;

package/dist/explorer/views/PageView.svelte

@@ -23,7 +23,7 @@
 </script>
 
 <div class="sdocs-page-view">
-	<div class="sdocs-page-main">
+	<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>
@@ -41,7 +41,7 @@
 	</div>
 
 	<!-- Table of Contents -->
-	{#if toc.length > 0}
+	{#if toc.length > 0 && doc.showToc !== false}
 		<aside class="sdocs-toc">
 			<h3 class="sdocs-toc-title">On this page</h3>
 			<nav>

package/dist/grammar/sdoc.tmLanguage.json

@@ -5,6 +5,18 @@
 	"fileTypes": [
 		"sdoc"
 	],
+	"injections": {
+		"L:meta.embedded.block.markdown - (markup.fenced_code.block.markdown, markup.inline.raw.string.markdown, meta.template.block.sdoc)": {
+			"patterns": [
+				{
+					"include": "#page-svelte-tag"
+				},
+				{
+					"include": "#page-svelte-expression"
+				}
+			]
+		}
+	},
 	"patterns": [
 		{
 			"include": "#comment"
@@ -232,6 +244,9 @@
 					"while": "(^|\\G)(?!\\s*\\[/PAGE\\]\\s*$)(?:\\t|[ ]{1,4})?",
 					"contentName": "meta.embedded.block.markdown",
 					"patterns": [
+						{
+							"include": "#page-svelte-block"
+						},
 						{
 							"include": "text.html.markdown"
 						}
@@ -239,6 +254,79 @@
 				}
 			]
 		},
+		"page-svelte-block": {
+			"name": "meta.template.block.sdoc",
+			"begin": "(\\{#[a-zA-Z]+)([^}]*)(\\})",
+			"beginCaptures": {
+				"1": {
+					"name": "keyword.control.svelte.sdoc"
+				},
+				"2": {
+					"patterns": [
+						{
+							"include": "source.ts"
+						}
+					]
+				},
+				"3": {
+					"name": "keyword.control.svelte.sdoc"
+				}
+			},
+			"end": "(\\{/[a-zA-Z]+\\})",
+			"endCaptures": {
+				"1": {
+					"name": "keyword.control.svelte.sdoc"
+				}
+			},
+			"patterns": [
+				{
+					"include": "source.svelte"
+				}
+			]
+		},
+		"page-svelte-tag": {
+			"name": "meta.template.block.sdoc",
+			"begin": "(\\{)([@:][a-zA-Z]+)",
+			"beginCaptures": {
+				"1": {
+					"name": "punctuation.definition.block.begin.sdoc"
+				},
+				"2": {
+					"name": "keyword.control.svelte.sdoc"
+				}
+			},
+			"end": "(\\})",
+			"endCaptures": {
+				"1": {
+					"name": "punctuation.definition.block.end.sdoc"
+				}
+			},
+			"patterns": [
+				{
+					"include": "source.ts"
+				}
+			]
+		},
+		"page-svelte-expression": {
+			"name": "meta.template.expression.sdoc",
+			"begin": "(\\{)(?![#/@:\\s}])(?=[^{}]*\\})",
+			"beginCaptures": {
+				"1": {
+					"name": "punctuation.definition.expression.begin.sdoc"
+				}
+			},
+			"end": "(\\})",
+			"endCaptures": {
+				"1": {
+					"name": "punctuation.definition.expression.end.sdoc"
+				}
+			},
+			"patterns": [
+				{
+					"include": "source.ts"
+				}
+			]
+		},
 		"layout": {
 			"name": "meta.block.layout.sdoc",
 			"begin": "^\\s*(\\[)(LAYOUT)\\b(.*)$",

package/dist/language/index.d.ts

@@ -1,3 +1,4 @@
 export { scanSdoc, offsetToPosition, ENTITY_KINDS, SUB_BLOCK_KINDS, type Span, type EntityKind, type SubBlockKind, type AttrValue, type Attrs, type SubBlock, type Entity, type TagBlock, type ScanError, type SdocFile, } from './scanner.js';
 export { projectSdoc, type SdocProjection, type ProjectedLineKind, } from './projection.js';
-export { parseSdoc, parseArgsLiteral, slugifyTitle, normalizeBody, type ArgValue, type PreviewBlock, type ExampleBlock, type DocsEntity, type PageEntity, type LayoutEntity, type SdocEntity, type SdocDocument, } from './parser.js';
+export { segmentPageBody, type PageSegment, } from './page-islands.js';
+export { parseSdoc, parseArgsLiteral, slugifyTitle, normalizeBody, type ArgValue, type Sizing, type PreviewBlock, type ExampleBlock, type DocsEntity, type PageEntity, type LayoutEntity, type SdocEntity, type SdocDocument, } from './parser.js';

package/dist/language/index.js

@@ -1,3 +1,4 @@
 export { scanSdoc, offsetToPosition, ENTITY_KINDS, SUB_BLOCK_KINDS, } from './scanner.js';
 export { projectSdoc, } from './projection.js';
+export { segmentPageBody, } from './page-islands.js';
 export { parseSdoc, parseArgsLiteral, slugifyTitle, normalizeBody, } from './parser.js';

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

@@ -0,0 +1,23 @@
+/**
+ * Island segmentation for [PAGE] bodies.
+ *
+ * A page body is markdown prose interleaved with Svelte "islands" — component
+ * tags, HTML sections, and template blocks like {#snippet}…{/snippet}. Markdown
+ * tooling (the renderer, prettier) must never look inside an island: markdown's
+ * paragraph and HTML-block rules split Svelte structure apart (a snippet opened
+ * inside a <p> and closed outside fails to compile; a blank line cuts a <div>
+ * section in half; a formatter re-indents block lines it can't understand).
+ *
+ * The rule an author sees: a line that starts a Svelte block ({#…}, {@render …})
+ * or an HTML/component tag, sitting at the start of a markdown block (preceded
+ * by a blank line or the body edge), begins an island. The island runs until
+ * its Svelte blocks and HTML tags are balanced — blank lines inside are part of
+ * the island. Everything else is prose.
+ */
+export interface PageSegment {
+    kind: 'prose' | 'island';
+    /** Verbatim lines of the segment */
+    lines: string[];
+}
+/** Split a page body into prose and island segments. */
+export declare function segmentPageBody(body: string): PageSegment[];

package/dist/language/page-islands.js

@@ -0,0 +1,122 @@
+/**
+ * Island segmentation for [PAGE] bodies.
+ *
+ * A page body is markdown prose interleaved with Svelte "islands" — component
+ * tags, HTML sections, and template blocks like {#snippet}…{/snippet}. Markdown
+ * tooling (the renderer, prettier) must never look inside an island: markdown's
+ * paragraph and HTML-block rules split Svelte structure apart (a snippet opened
+ * inside a <p> and closed outside fails to compile; a blank line cuts a <div>
+ * section in half; a formatter re-indents block lines it can't understand).
+ *
+ * The rule an author sees: a line that starts a Svelte block ({#…}, {@render …})
+ * or an HTML/component tag, sitting at the start of a markdown block (preceded
+ * by a blank line or the body edge), begins an island. The island runs until
+ * its Svelte blocks and HTML tags are balanced — blank lines inside are part of
+ * the island. Everything else is prose.
+ */
+/** Void elements never contribute to tag depth. */
+const VOID_TAGS = new Set([
+    'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
+    'link', 'meta', 'param', 'source', 'track', 'wbr',
+]);
+/** Does this line begin an island (at a markdown block start)? */
+function startsIsland(line) {
+    const t = line.trimStart();
+    return /^\{[#/@]/.test(t) || /^<[A-Za-z]/.test(t) || /^<\//.test(t);
+}
+/**
+ * Net Svelte block depth and HTML tag depth contributed by one line.
+ * Line-based and heuristic by design: quoted attribute values are skipped,
+ * self-closing and void tags are neutral. Unbalanced input never throws —
+ * the island simply extends (and Svelte reports the real error).
+ */
+function lineDepths(line) {
+    let svelte = 0;
+    let html = 0;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (ch === '"' || ch === "'" || ch === '`') {
+            for (i++; i < line.length && line[i] !== ch; i++) {
+                if (line[i] === '\\')
+                    i++;
+            }
+            continue;
+        }
+        if (ch === '{') {
+            if (line[i + 1] === '#')
+                svelte++;
+            else if (line[i + 1] === '/')
+                svelte--;
+            continue;
+        }
+        if (ch !== '<')
+            continue;
+        const rest = line.slice(i);
+        const close = rest.match(/^<\/([A-Za-z][A-Za-z0-9-]*)/);
+        if (close) {
+            if (!VOID_TAGS.has(close[1].toLowerCase()))
+                html--;
+            continue;
+        }
+        const open = rest.match(/^<([A-Za-z][A-Za-z0-9-]*)/);
+        if (!open)
+            continue;
+        if (VOID_TAGS.has(open[1].toLowerCase()))
+            continue;
+        // Find the tag's own '>' (skipping quoted attrs) to detect self-closing.
+        let j = i + open[0].length;
+        for (; j < line.length; j++) {
+            const c = line[j];
+            if (c === '"' || c === "'") {
+                for (j++; j < line.length && line[j] !== c; j++)
+                    ;
+            }
+            else if (c === '>')
+                break;
+        }
+        if (j >= line.length || line[j - 1] !== '/')
+            html++;
+        // Self-closing (`/>`) is neutral; an unterminated tag counts as open.
+    }
+    return { svelte, html };
+}
+/** Split a page body into prose and island segments. */
+export function segmentPageBody(body) {
+    const lines = body.split('\n');
+    const segments = [];
+    let current = null;
+    const push = (kind, line) => {
+        if (current?.kind !== kind) {
+            current = { kind, lines: [] };
+            segments.push(current);
+        }
+        current.lines.push(line);
+    };
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        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.
+            let svelte = 0;
+            let html = 0;
+            let j = i;
+            for (; j < lines.length; j++) {
+                const d = lineDepths(lines[j]);
+                svelte += d.svelte;
+                html += d.html;
+                if (svelte <= 0 && html <= 0)
+                    break;
+            }
+            const end = Math.min(j, lines.length - 1);
+            for (let k = i; k <= end; k++)
+                push('island', lines[k]);
+            current = null; // consecutive islands stay separate segments
+            i = end + 1;
+            continue;
+        }
+        push('prose', line);
+        i++;
+    }
+    return segments;
+}

package/dist/language/parser.d.ts

@@ -5,6 +5,17 @@
  */
 import { type ScanError, type Span, type TagBlock } from './scanner.js';
 export type ArgValue = string | number | boolean;
+/** Explicit presentation overrides from stage attributes */
+export interface Sizing {
+    maxWidth: string | null;
+    padding: string | null;
+    /** flex-direction of preview/example stages */
+    direction: string | null;
+    /** gap of preview/example stages */
+    gap: string | null;
+    /** table-of-contents visibility (PAGE) */
+    toc: boolean | null;
+}
 export interface PreviewBlock {
     /** The identifier from component={X}; null when invalid/missing (already reported) */
     componentName: string | null;
@@ -16,12 +27,14 @@ export interface PreviewBlock {
     title: string | null;
     /** Tab label: the title override or the component name */
     label: string;
+    sizing: Sizing;
     body: string;
     bodySpan: Span;
     span: Span;
 }
 export interface ExampleBlock {
     title: string;
+    sizing: Sizing;
     body: string;
     bodySpan: Span;
     span: Span;
@@ -31,6 +44,7 @@ export interface DocsEntity {
     title: string;
     slug: string;
     description: string | null;
+    sizing: Sizing;
     previews: PreviewBlock[];
     examples: ExampleBlock[];
     openerSpan: Span;
@@ -40,6 +54,7 @@ export interface PageEntity {
     kind: 'PAGE';
     title: string;
     slug: string;
+    sizing: Sizing;
     body: string;
     bodySpan: Span;
     openerSpan: Span;
@@ -49,7 +64,7 @@ export interface LayoutEntity {
     kind: 'LAYOUT';
     title: string;
     slug: string;
-    padding: string | null;
+    sizing: Sizing;
     body: string;
     bodySpan: Span;
     openerSpan: Span;

package/dist/language/parser.js

@@ -43,17 +43,39 @@ export function slugifyTitle(title) {
         .replace(/^-+|-+$/g, '') || 'untitled');
 }
 const IDENTIFIER_RE = /^[A-Z][A-Za-z0-9_]*$/;
+const SIZING_ATTR_RULES = {
+    maxWidth: { required: false, kind: 'string', hint: 'maxWidth="1200px"' },
+    padding: { required: false, kind: 'string', hint: 'padding="32px"' },
+};
+const STAGE_LAYOUT_ATTR_RULES = {
+    direction: { required: false, kind: 'string', hint: 'direction="column"' },
+    gap: { required: false, kind: 'string', hint: 'gap="16px"' },
+};
+function sizingOf(attrs) {
+    const toc = stringAttr(attrs, 'toc');
+    return {
+        maxWidth: stringAttr(attrs, 'maxWidth'),
+        padding: stringAttr(attrs, 'padding'),
+        direction: stringAttr(attrs, 'direction'),
+        gap: stringAttr(attrs, 'gap'),
+        toc: toc === null ? null : toc === 'true',
+    };
+}
 const ENTITY_ATTR_RULES = {
     DOCS: {
         title: { required: true, kind: 'string', hint: 'title="Group / Name"' },
         description: { required: false, kind: 'string', hint: 'description="…"' },
+        ...SIZING_ATTR_RULES,
+        ...STAGE_LAYOUT_ATTR_RULES,
     },
     PAGE: {
         title: { required: true, kind: 'string', hint: 'title="Group / Name"' },
+        ...SIZING_ATTR_RULES,
+        toc: { required: false, kind: 'string', hint: 'toc="false"' },
     },
     LAYOUT: {
         title: { required: true, kind: 'string', hint: 'title="Group / Name"' },
-        padding: { required: false, kind: 'string', hint: 'padding="48px"' },
+        ...SIZING_ATTR_RULES,
     },
 };
 const SUB_BLOCK_ATTR_RULES = {
@@ -61,9 +83,13 @@ const SUB_BLOCK_ATTR_RULES = {
         component: { required: true, kind: 'expression', hint: 'component={Button}' },
         args: { required: false, kind: 'expression', hint: 'args={{ label: "Hi" }}' },
         title: { required: false, kind: 'string', hint: 'title="…"' },
+        ...SIZING_ATTR_RULES,
+        ...STAGE_LAYOUT_ATTR_RULES,
     },
     example: {
         title: { required: true, kind: 'string', hint: 'title="…"' },
+        ...SIZING_ATTR_RULES,
+        ...STAGE_LAYOUT_ATTR_RULES,
     },
 };
 function checkAttrs(owner, attrs, rules, ownerSpan, diagnostics) {
@@ -192,6 +218,7 @@ function parsePreview(block, diagnostics) {
         argsRaw,
         title,
         label: title ?? componentName ?? 'Preview',
+        sizing: sizingOf(block.attrs),
         body: normalizeBody(block.body),
         bodySpan: block.bodySpan,
         span: block.span,
@@ -229,6 +256,7 @@ function parseDocs(entity, diagnostics) {
             exampleTitles.add(title);
             examples.push({
                 title,
+                sizing: sizingOf(block.attrs),
                 body: normalizeBody(block.body),
                 bodySpan: block.bodySpan,
                 span: block.span,
@@ -241,6 +269,7 @@ function parseDocs(entity, diagnostics) {
         title,
         slug: slugifyTitle(title),
         description: stringAttr(entity.attrs, 'description'),
+        sizing: sizingOf(entity.attrs),
         previews,
         examples,
         openerSpan: entity.openerSpan,
@@ -263,15 +292,13 @@ export function parseSdoc(source) {
             const base = {
                 title,
                 slug: slugifyTitle(title),
+                sizing: sizingOf(entity.attrs),
                 body: normalizeBody(entity.body),
                 bodySpan: entity.bodySpan,
                 openerSpan: entity.openerSpan,
                 span: entity.span,
             };
-            typed =
-                entity.kind === 'PAGE'
-                    ? { kind: 'PAGE', ...base }
-                    : { kind: 'LAYOUT', padding: stringAttr(entity.attrs, 'padding'), ...base };
+            typed = entity.kind === 'PAGE' ? { kind: 'PAGE', ...base } : { kind: 'LAYOUT', ...base };
         }
         if (slugs.has(typed.slug)) {
             diagnostics.push({

package/dist/server/config.js

@@ -13,6 +13,11 @@ const DEFAULTS = {
         order: {},
         open: [],
     },
+    content: {
+        page: { maxWidth: '1200px', padding: '32px', toc: true },
+        docs: { maxWidth: '1200px', padding: '16px', direction: 'row', gap: '16px' },
+        layout: { maxWidth: '100%', padding: '0px' },
+    },
 };
 /** Find the config file path in the given directory */
 export function findConfigFile(root) {
@@ -83,5 +88,10 @@ export function resolveConfig(userConfig) {
             order: userConfig.sidebar?.order ?? DEFAULTS.sidebar.order,
             open: userConfig.sidebar?.open ?? DEFAULTS.sidebar.open,
         },
+        content: {
+            page: { ...DEFAULTS.content.page, ...userConfig.content?.page },
+            docs: { ...DEFAULTS.content.docs, ...userConfig.content?.docs },
+            layout: { ...DEFAULTS.content.layout, ...userConfig.content?.layout },
+        },
     };
 }

package/dist/server/page-markdown.d.ts

@@ -12,4 +12,11 @@ export interface RenderedPage {
     html: string;
     toc: TocHeading[];
 }
+/**
+ * Render a [PAGE] body: Svelte islands (see segmentPageBody) pass through
+ * verbatim — markdown never splits a snippet or an HTML section — and the
+ * prose between them renders as markdown. Islands land at the top level of
+ * the compiled fragment, so a snippet declared anywhere is renderable from
+ * anywhere on the page.
+ */
 export declare function renderPageMarkdown(source: string): Promise<RenderedPage>;

package/dist/server/page-markdown.js

@@ -9,6 +9,7 @@
  */
 import { Marked } from 'marked';
 import { highlight } from './highlighter.js';
+import { segmentPageBody } from '../language/page-islands.js';
 function slugify(text) {
     return (text
         .toLowerCase()
@@ -86,9 +87,28 @@ function plainText(tokens) {
     }
     return out;
 }
+/**
+ * Render a [PAGE] body: Svelte islands (see segmentPageBody) pass through
+ * verbatim — markdown never splits a snippet or an HTML section — and the
+ * prose between them renders as markdown. Islands land at the top level of
+ * the compiled fragment, so a snippet declared anywhere is renderable from
+ * anywhere on the page.
+ */
 export async function renderPageMarkdown(source) {
     const toc = [];
     const usedIds = new Set();
+    const parts = [];
+    for (const segment of segmentPageBody(source)) {
+        if (segment.kind === 'island') {
+            parts.push(segment.lines.join('\n'));
+        }
+        else {
+            parts.push(await renderProse(segment.lines.join('\n'), toc, usedIds));
+        }
+    }
+    return { html: parts.join('\n'), toc };
+}
+async function renderProse(source, toc, usedIds) {
     const headingIds = new WeakMap();
     const fenceHtml = new WeakMap();
     const marked = new Marked({ gfm: true });
@@ -161,5 +181,5 @@ export async function renderPageMarkdown(source) {
             }
         }
     });
-    return { html: marked.parser(tokens), toc };
+    return marked.parser(tokens);
 }

package/dist/server/snippet-compiler.d.ts

@@ -23,7 +23,12 @@ export declare function resolveScriptImports(script: string, docFilePath: string
 /** Generate a virtual Svelte iframe wrapper component for a snippet.
  * Includes $state for reactive prop updates via postMessage, invokes
  * component methods on request, and broadcasts exported state values. */
-export declare function generateIframeComponent(scriptPrelude: string, snippetBody: string, stateNames?: string[], componentName?: string): string;
+export declare function generateIframeComponent(scriptPrelude: string, snippetBody: string, stateNames?: string[], componentName?: string, stage?: {
+    maxWidth: string;
+    padding: string;
+    direction?: string;
+    gap?: string;
+}): string;
 /** The JS that boots a preview page: mount the wrapper + parent-frame messaging. */
 export declare function generateMountScript(iframeComponentId: string): string;
 /** Generate the HTML page served inside the iframe (dev / CLI-build inputs) */

package/dist/server/snippet-compiler.js

@@ -81,7 +81,27 @@ function injectRootRef(snippetBody, componentName) {
 /** Generate a virtual Svelte iframe wrapper component for a snippet.
  * Includes $state for reactive prop updates via postMessage, invokes
  * component methods on request, and broadcasts exported state values. */
-export function generateIframeComponent(scriptPrelude, snippetBody, stateNames = [], componentName) {
+export function generateIframeComponent(scriptPrelude, snippetBody, stateNames = [], componentName, stage) {
+    // The stage layout (config -> entity -> block cascade) applies here, inside
+    // the iframe, so every consumer of the preview page gets it. Preview and
+    // example stages are flex containers (direction + gap); page and layout
+    // stages are flow-root blocks. Both contain child margins, so the height
+    // reported for iframe auto-sizing is exact.
+    const stageStyle = [
+        ...(stage?.direction
+            ? [
+                'display: flex',
+                `flex-direction: ${stage.direction}`,
+                'flex-wrap: wrap',
+                'align-items: flex-start',
+                `gap: ${stage.gap}`,
+            ]
+            : ['display: flow-root']),
+        ...(stage ? [`padding: ${stage.padding}`] : []),
+        ...(stage && stage.maxWidth !== '100%'
+            ? [`max-width: ${stage.maxWidth}`, 'margin-inline: auto']
+            : []),
+    ].join('; ');
     // The file <script> (imports + shared values), lifted verbatim so previews
     // and examples see everything the entity's siblings do.
     const importBlock = scriptPrelude.trim() ? scriptPrelude.trim() + '\n' : '';
@@ -151,7 +171,7 @@ ${stateBroadcast}
 	});
 </script>
 
-<div id="sdocs-preview" style="display: flow-root">
+<div id="sdocs-preview" style="${stageStyle}">
 	{#snippet SdocsPreview(args)}
 		${injectRootRef(snippetBody, componentName)}
 	{/snippet}

package/dist/types.d.ts

@@ -19,6 +19,38 @@ export interface SdocsConfig {
         /** Folders expanded by default on load. */
         open?: string[];
     };
+    /** Content presentation per entity kind; entity/block attributes override these. */
+    content?: {
+        /** [PAGE] content. Defaults: maxWidth '1200px', padding '32px', toc true. */
+        page?: ContentSizing & {
+            /** Show the table of contents. Default: true */
+            toc?: boolean;
+        };
+        /** [DOCS] pages: maxWidth is the content column (default '1200px');
+         * padding/direction/gap are the default preview/example stage layout
+         * (defaults '16px', 'row', '16px'). */
+        docs?: ContentSizing & {
+            /** Stage flex-direction. Default: 'row' */
+            direction?: string;
+            /** Stage gap. Default: '16px' */
+            gap?: string;
+        };
+        /** [LAYOUT] stages. Defaults: maxWidth '100%', padding '0px'. */
+        layout?: ContentSizing;
+    };
+}
+/** Content sizing knobs (any CSS length; padding takes CSS shorthand) */
+export interface ContentSizing {
+    maxWidth?: string;
+    padding?: string;
+}
+/** Resolved stage layout applied inside a preview iframe */
+export interface StageLayout {
+    maxWidth: string;
+    padding: string;
+    /** flex-direction + gap; set for preview/example stages only */
+    direction?: string;
+    gap?: string;
 }
 /** Resolved config with all defaults applied */
 export interface ResolvedSdocsConfig {
@@ -32,6 +64,16 @@ export interface ResolvedSdocsConfig {
         order: Record<string, string[]>;
         open: string[];
     };
+    content: {
+        page: Required<ContentSizing> & {
+            toc: boolean;
+        };
+        docs: Required<ContentSizing> & {
+            direction: string;
+            gap: string;
+        };
+        layout: Required<ContentSizing>;
+    };
 }
 /** Entity metadata from a [DOCS]/[PAGE]/[LAYOUT] opener */
 export interface SdocMeta {
@@ -87,6 +129,8 @@ export interface ExtractedSnippet {
     highlightedHtml?: string;
     /** Preview URL for iframe (added by virtual module) */
     previewUrl?: string;
+    /** Resolved stage layout applied inside the iframe (config → entity → block) */
+    stage?: StageLayout;
 }
 /** One [preview] of a DOCS entity: a live showcase of one component */
 export interface PreviewEntry {
@@ -128,6 +172,8 @@ export interface DocEntry {
     content: ExtractedSnippet | null;
     /** Table of contents headings (pages only) */
     toc?: TocHeading[];
-    /** Stage padding (layouts only) */
-    padding?: string | null;
+    /** Resolved content-column max width (component and page kinds) */
+    maxWidth?: string;
+    /** Resolved table-of-contents visibility (pages only) */
+    showToc?: boolean;
 }

package/dist/vite.js

@@ -228,7 +228,7 @@ export function sdocsPlugin(userConfig) {
                 // example iframes fall back to the first preview's component.
                 const preview = entry.previews.find((p) => p.snippet.slug === snippet.slug) ?? entry.previews[0];
                 const stateNames = (preview?.componentData?.state ?? []).map((s) => s.name);
-                return generateIframeComponent(scriptPrelude, snippet.body, stateNames, preview?.componentName ?? undefined);
+                return generateIframeComponent(scriptPrelude, snippet.body, stateNames, preview?.componentName ?? undefined, snippet.stage);
             }
             // Virtual mount script for an emitted preview page
             if (id.startsWith('\0' + MOUNT_PREFIX)) {
@@ -299,6 +299,27 @@ export function sdocsPlugin(userConfig) {
                 examples: [],
                 content: null,
             };
+            // Sizing cascade: block attribute -> entity attribute -> config default.
+            const kindKey = entity.kind === 'DOCS' ? 'docs' : entity.kind === 'PAGE' ? 'page' : 'layout';
+            const kindDefaults = config.content[kindKey];
+            const stageOf = (block) => ({
+                // Entity-level maxWidth on DOCS/PAGE is the content column, not the
+                // stage; stages inside them span their panel unless the block says so.
+                maxWidth: block?.maxWidth ??
+                    (entity.kind === 'LAYOUT' ? (entity.sizing.maxWidth ?? kindDefaults.maxWidth) : '100%'),
+                padding: block?.padding ?? entity.sizing.padding ?? kindDefaults.padding,
+                // direction/gap flex the preview/example stages only
+                ...(entity.kind === 'DOCS' && block
+                    ? {
+                        direction: block.direction ?? entity.sizing.direction ?? config.content.docs.direction,
+                        gap: block.gap ?? entity.sizing.gap ?? config.content.docs.gap,
+                    }
+                    : {}),
+            });
+            entry.maxWidth = entity.sizing.maxWidth ?? kindDefaults.maxWidth;
+            if (entity.kind === 'PAGE') {
+                entry.showToc = entity.sizing.toc ?? config.content.page.toc;
+            }
             if (entity.kind === 'DOCS') {
                 if (entity.description)
                     entry.meta.description = entity.description;
@@ -318,6 +339,7 @@ export function sdocsPlugin(userConfig) {
                             console.warn(`[sdocs] ${filePath}: component {${preview.componentName}} is not imported in the file's <script>`);
                         }
                     }
+                    snippet.stage = stageOf(preview.sizing);
                     snippet.highlightedHtml = await highlight(snippet.body);
                     entry.previews.push({
                         label: preview.label,
@@ -330,6 +352,10 @@ export function sdocsPlugin(userConfig) {
                     });
                 }
                 entry.examples = snippets.filter((s) => s.role === 'example');
+                entity.examples.forEach((example, i) => {
+                    if (entry.examples[i])
+                        entry.examples[i].stage = stageOf(example.sizing);
+                });
                 for (const example of entry.examples) {
                     example.highlightedHtml = await highlight(example.body);
                 }
@@ -337,12 +363,13 @@ export function sdocsPlugin(userConfig) {
             else if (entity.kind === 'PAGE') {
                 const rendered = await renderPageMarkdown(entity.body);
                 snippets[0].body = rendered.html;
+                snippets[0].stage = stageOf();
                 entry.content = snippets[0];
                 entry.toc = rendered.toc;
             }
             else {
+                snippets[0].stage = stageOf();
                 entry.content = snippets[0];
-                entry.padding = entity.padding;
             }
             docEntries.set(entityKey(filePath, entity.slug), entry);
         }
@@ -369,7 +396,8 @@ export function sdocsPlugin(userConfig) {
             examples: e.examples.map((s) => withUrl(e, s)),
             content: e.content ? withUrl(e, e.content) : null,
             toc: e.toc,
-            padding: e.padding,
+            maxWidth: e.maxWidth,
+            showToc: e.showToc,
         }));
         // Extract named CSS stylesheet names (empty array if single string or null)
         const cssNames = config.css && typeof config.css === 'object'

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "sdocs",
-	"version": "0.0.51",
+	"version": "0.0.53",
 	"description": "A lightweight documentation tool for Svelte 5 components",
 	"type": "module",
 	"license": "MIT",