sdocs 0.0.57 → 0.0.58

package/CHANGELOG.md

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

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/views/PageView.svelte

@@ -40,6 +40,11 @@
 	function scrollToHeading(id: string) {
 		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>
 
 {#snippet exampleFrame(index: number)}
@@ -65,52 +70,61 @@
 {/snippet}
 
 <div class="sdocs-page-view" style:padding={doc.padding}>
-	<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>
+	<!-- 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}
-		</div>
 
-		<!-- Content -->
-		<div class="sdocs-page-content" bind:this={container}>
-			{#if PageComponent}
-				<PageComponent __sdocsExample={exampleFrame} />
-			{/if}
+			<!-- Content -->
+			<div class="sdocs-page-content" bind:this={container}>
+				{#if PageComponent}
+					<PageComponent __sdocsExample={exampleFrame} />
+				{/if}
+			</div>
 		</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}
+		<!-- 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>
 </div>
 
 <style>
 	.sdocs-page-view {
-		display: flex;
-		gap: 24px;
 		/* padding comes from the doc entry (config/entity cascade) */
 		font-family: var(--sans);
 	}
+	.sdocs-page-inner {
+		display: flex;
+		gap: 24px;
+		/* max-width and margin (contentX) come from the doc entry */
+	}
 	.sdocs-page-main {
 		flex: 1;
 		min-width: 0;
@@ -207,6 +221,9 @@
 	.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) {
@@ -214,12 +231,61 @@
 		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 ── */

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.js

@@ -75,6 +75,8 @@ const ENTITY_ATTR_RULES = {
     PAGE: {
         title: { required: true, kind: 'string', hint: 'title="Group / Name"' },
         ...SIZING_ATTR_RULES,
+        // On PAGE, contentX aligns the content column (with its toc), not a stage.
+        contentX: { required: false, kind: 'string', hint: 'contentX="center"' },
         toc: { required: false, kind: 'string', hint: 'toc="false"' },
     },
     LAYOUT: {

package/dist/server/config.js

@@ -7,6 +7,7 @@ const DEFAULTS = {
     port: 3000,
     open: false,
     css: null,
+    static: null,
     logo: 'sdocs',
     icon: 'sdocs',
     sidebar: {
@@ -14,7 +15,7 @@ const DEFAULTS = {
         open: [],
     },
     content: {
-        page: { maxWidth: '1200px', padding: '32px', toc: true },
+        page: { maxWidth: '1200px', padding: '32px', toc: true, contentX: 'left' },
         docs: {
             maxWidth: '1200px',
             padding: '16px',
@@ -69,6 +70,8 @@ export function resolveAndFinalize(userConfig, root) {
     const resolved = resolveConfig(userConfig);
     resolved.include = resolveIncludePatterns(resolved.include, root);
     resolved.css = resolveCssPaths(resolved.css, root);
+    if (resolved.static)
+        resolved.static = resolve(root, resolved.static);
     return resolved;
 }
 /** Import a config file (.js/.mjs; .ts only on Node with native type stripping) */
@@ -89,6 +92,7 @@ export function resolveConfig(userConfig) {
         port: userConfig.port ?? DEFAULTS.port,
         open: userConfig.open ?? DEFAULTS.open,
         css: userConfig.css ?? DEFAULTS.css,
+        static: userConfig.static ?? DEFAULTS.static,
         logo: userConfig.logo ?? DEFAULTS.logo,
         icon: userConfig.icon ?? DEFAULTS.icon,
         sidebar: {

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

@@ -11,6 +11,9 @@ import type { TocHeading } from '../types.js';
 export interface RenderedPage {
     html: string;
     toc: TocHeading[];
+    /** Text of the body's first `#` heading, when present — it takes over as
+     * the page's displayed title. */
+    bodyTitle?: string;
 }
 /**
  * Render a [PAGE] body: Svelte islands (see segmentPageBody) pass through

package/dist/server/page-markdown.js

@@ -97,26 +97,56 @@ function plainText(tokens) {
 export async function renderPageMarkdown(source) {
     const toc = [];
     const usedIds = new Set();
+    const state = { toc, usedIds, bodyTitle: undefined };
     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));
+            parts.push(await renderProse(segment.lines.join('\n'), state));
         }
     }
-    return { html: parts.join('\n'), toc };
+    return { html: parts.join('\n'), toc, bodyTitle: state.bodyTitle };
 }
-async function renderProse(source, toc, usedIds) {
+/** GitHub-style alert kinds recognized on a blockquote's first line. */
+const ALERT_KINDS = ['NOTE', 'TIP', 'IMPORTANT', 'WARNING', 'CAUTION'];
+const ALERT_RE = new RegExp(`^\\[!(${ALERT_KINDS.join('|')})\\][ \\t]*(?:\\n|$)`);
+async function renderProse(source, state) {
+    const { toc, usedIds } = state;
     const headingIds = new WeakMap();
     const fenceHtml = new WeakMap();
+    const alertKinds = new WeakMap();
     const marked = new Marked({ gfm: true });
     const tokens = marked.lexer(source);
+    /** Detect a GitHub-style alert marker on a blockquote's first line and
+     * strip it from the tokens; the renderer wraps the rest as a callout. */
+    const detectAlert = (token) => {
+        if (!('tokens' in token) || !token.tokens)
+            return;
+        const para = token.tokens[0];
+        if (para?.type !== 'paragraph' || !para.tokens)
+            return;
+        const first = para.tokens[0];
+        if (first?.type !== 'text')
+            return;
+        const m = ALERT_RE.exec(first.text ?? '');
+        if (!m)
+            return;
+        alertKinds.set(token, m[1]);
+        first.text = first.text.slice(m[0].length);
+        if (first.text === '')
+            para.tokens.shift();
+        if (para.tokens.length === 0)
+            token.tokens.shift();
+    };
     const walk = (list) => {
         for (const token of list) {
             if (token.type === 'heading') {
                 const text = plainText(token.tokens ?? []);
+                if (token.depth === 1 && state.bodyTitle === undefined) {
+                    state.bodyTitle = text;
+                }
                 const baseId = slugify(text);
                 let id = baseId;
                 for (let n = 2; usedIds.has(id); n++)
@@ -127,6 +157,8 @@ async function renderProse(source, toc, usedIds) {
                     toc.push({ text, level: token.depth, id });
                 }
             }
+            if (token.type === 'blockquote')
+                detectAlert(token);
             if ('tokens' in token && token.tokens)
                 walk(token.tokens);
             if ('items' in token && token.items)
@@ -155,6 +187,31 @@ async function renderProse(source, toc, usedIds) {
                     ? `<h${token.depth} id="${id}">${html}</h${token.depth}>\n`
                     : `<h${token.depth}>${html}</h${token.depth}>\n`;
             },
+            // GitHub-style alerts: `> [!NOTE]` blockquotes become callouts.
+            blockquote(token) {
+                const body = this.parser.parse(token.tokens ?? []);
+                const kind = alertKinds.get(token);
+                if (!kind)
+                    return `<blockquote>\n${body}</blockquote>\n`;
+                const label = kind.charAt(0) + kind.slice(1).toLowerCase();
+                return `<div class="sdocs-alert sdocs-alert-${kind.toLowerCase()}"><p class="sdocs-alert-label">${label}</p>\n${body}</div>\n`;
+            },
+            // External links open away from the docs app; hrefs stay inert.
+            link(token) {
+                const inner = this.parser.parseInline(token.tokens ?? []);
+                const href = escapeBraces(escapeHtml(token.href ?? ''));
+                const title = token.title ? ` title="${escapeBraces(escapeHtml(token.title))}"` : '';
+                const external = /^https?:\/\//i.test(token.href ?? '');
+                const attrs = external ? ' target="_blank" rel="noopener noreferrer"' : '';
+                return `<a href="${href}"${title}${attrs}>${inner}</a>`;
+            },
+            // Self-closing and brace-escaped so images are always Svelte-safe.
+            image(token) {
+                const src = escapeBraces(escapeHtml(token.href ?? ''));
+                const alt = escapeBraces(escapeHtml(token.text ?? ''));
+                const title = token.title ? ` title="${escapeBraces(escapeHtml(token.title))}"` : '';
+                return `<img src="${src}" alt="${alt}"${title} loading="lazy" />`;
+            },
             code(token) {
                 return (fenceHtml.get(token) ??
                     `<pre><code>${escapeBraces(escapeHtml(token.text))}</code></pre>\n`);

package/dist/types.d.ts

@@ -8,6 +8,10 @@ export interface SdocsConfig {
     open?: boolean;
     /** CSS loaded in preview iframes. Single path or named stylesheets. */
     css?: string | Record<string, string>;
+    /** Folder of static assets served at the site root — images for pages,
+     * files for previews. Standalone CLI flows (`sdocs dev`/`build`); when
+     * embedding the Vite plugin, use the host app's own public directory. */
+    static?: string;
     /** Sidebar logo text. Default: 'sdocs' */
     logo?: string;
     /** Sidebar logo icon: 'sdocs' for the built-in mascot, an image URL, or false to hide. Default: 'sdocs' */
@@ -25,6 +29,9 @@ export interface SdocsConfig {
         page?: ContentSizing & {
             /** Show the table of contents. Default: true */
             toc?: boolean;
+            /** Horizontal alignment of the content column (with its toc) inside
+             * the view: 'left'|'center'|'right'. Default: 'left' */
+            contentX?: string;
         };
         /** [DOCS] pages: maxWidth is the content column (default '1200px');
          * padding/direction/gap are the default preview/example stage layout
@@ -66,6 +73,7 @@ export interface ResolvedSdocsConfig {
     port: number;
     open: boolean;
     css: string | Record<string, string> | null;
+    static: string | null;
     logo: string;
     icon: string | false;
     sidebar: {
@@ -75,6 +83,7 @@ export interface ResolvedSdocsConfig {
     content: {
         page: Required<ContentSizing> & {
             toc: boolean;
+            contentX: string;
         };
         docs: Required<ContentSizing> & {
             direction: string;
@@ -186,8 +195,13 @@ export interface DocEntry {
     maxWidth?: string;
     /** Resolved page padding (pages only) */
     padding?: string;
+    /** Resolved horizontal alignment of the content column (pages only) */
+    contentX?: string;
     /** Resolved table-of-contents visibility (pages only) */
     showToc?: boolean;
+    /** The body's `#` heading, shown as the page title instead of the entity
+     * title (pages only) */
+    bodyTitle?: string;
     /** Key into the virtual module's pageModules map (pages only) */
     contentKey?: string;
 }

package/dist/vite.js

@@ -386,6 +386,8 @@ export function sdocsPlugin(userConfig) {
                 entry.content = snippets[0];
                 entry.toc = rendered.toc;
                 entry.padding = entity.sizing.padding ?? config.content.page.padding;
+                entry.contentX = entity.sizing.contentX ?? config.content.page.contentX;
+                entry.bodyTitle = rendered.bodyTitle;
                 entry.contentKey = encodeEntityId(filePath, entity.slug);
                 entry.examples = snippets.filter((s) => s.role === 'example');
                 entity.examples.forEach((example, i) => {
@@ -436,7 +438,9 @@ export function sdocsPlugin(userConfig) {
             toc: e.toc,
             maxWidth: e.maxWidth,
             padding: e.padding,
+            contentX: e.contentX,
             showToc: e.showToc,
+            bodyTitle: e.bodyTitle,
             contentKey: e.contentKey,
         }));
         // Extract named CSS stylesheet names (empty array if single string or null)

package/package.json

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