sdocs 0.0.52 → 0.0.53

package/CHANGELOG.md

@@ -7,6 +7,23 @@ 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

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/language/index.d.ts

@@ -1,4 +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 { segmentPageBody, type PageSegment, } from './page-islands.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 { 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/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/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.52",
+	"version": "0.0.53",
 	"description": "A lightweight documentation tool for Svelte 5 components",
 	"type": "module",
 	"license": "MIT",