sdocs 0.0.56 → 0.0.58

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;
@@ -176,7 +185,7 @@ export interface DocEntry {
     meta: SdocMeta;
     /** Live previews (component kind; empty otherwise) */
     previews: PreviewEntry[];
-    /** Frozen examples (component kind; empty otherwise) */
+    /** Frozen examples (component and page kinds; empty otherwise) */
     examples: ExtractedSnippet[];
     /** The rendered body (page/layout kind; null otherwise) */
     content: ExtractedSnippet | null;
@@ -184,6 +193,15 @@ export interface DocEntry {
     toc?: TocHeading[];
     /** Resolved content-column max width (component and page kinds) */
     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

@@ -6,18 +6,20 @@ import { parseSdoc, offsetToPosition } from './language/index.js';
 import { planEntitySnippets, extractImports, resolveComponentImport, } from './server/doc-model.js';
 import { renderPageMarkdown } from './server/page-markdown.js';
 import { highlight, disposeHighlighter } from './server/highlighter.js';
-import { parseIframeId, parseMountId, parsePreviewUrl, resolveScriptImports, generateIframeComponent, generateMountScript, generatePreviewHtml, generateStaticPreviewHtml, iframeVirtualId, mountVirtualId, previewUrl, buildPreviewUrl, encodeEntityId, entityKey, setDocPathRoot, } from './server/snippet-compiler.js';
+import { parseIframeId, parseMountId, parsePageId, parsePreviewUrl, resolveScriptImports, generateIframeComponent, generateMountScript, generatePageComponent, generatePreviewHtml, generateStaticPreviewHtml, iframeVirtualId, mountVirtualId, pageVirtualId, previewUrl, buildPreviewUrl, encodeEntityId, entityKey, setDocPathRoot, } from './server/snippet-compiler.js';
 const VIRTUAL_MODULE_ID = 'virtual:sdocs';
 const RESOLVED_VIRTUAL_ID = '\0virtual:sdocs';
 const IFRAME_PREFIX = '/@sdocs/iframe/';
 const PREVIEW_PREFIX = '/@sdocs/preview/';
 const MOUNT_PREFIX = '/@sdocs/mount/';
-/** Every renderable snippet of an entry, in order. */
+const PAGE_PREFIX = '/@sdocs/page/';
+/** Every iframe-served snippet of an entry, in order. A PAGE's content
+ * renders natively in the Explorer (via pageModules), never as an iframe. */
 function allSnippets(entry) {
     return [
         ...entry.previews.map((p) => p.snippet),
         ...entry.examples,
-        ...(entry.content ? [entry.content] : []),
+        ...(entry.content && entry.kind !== 'page' ? [entry.content] : []),
     ];
 }
 export function sdocsPlugin(userConfig) {
@@ -206,6 +208,8 @@ export function sdocsPlugin(userConfig) {
                 return '\0' + id;
             if (id.startsWith(MOUNT_PREFIX))
                 return '\0' + id;
+            if (id.startsWith(PAGE_PREFIX))
+                return '\0' + id;
         },
         load(id) {
             if (id === RESOLVED_VIRTUAL_ID) {
@@ -230,6 +234,17 @@ export function sdocsPlugin(userConfig) {
                 const stateNames = (preview?.componentData?.state ?? []).map((s) => s.name);
                 return generateIframeComponent(scriptPrelude, snippet.body, stateNames, preview?.componentName ?? undefined, snippet.stage);
             }
+            // Virtual native content component for a PAGE entity
+            if (id.startsWith('\0' + PAGE_PREFIX)) {
+                const parsed = parsePageId(id.slice(1));
+                if (!parsed)
+                    return null;
+                const entry = docEntries.get(entityKey(parsed.docFilePath, parsed.entitySlug));
+                if (!entry?.content)
+                    return null;
+                const scriptPrelude = docScriptCache.get(parsed.docFilePath) ?? '';
+                return generatePageComponent(scriptPrelude, entry.content.body);
+            }
             // Virtual mount script for an emitted preview page
             if (id.startsWith('\0' + MOUNT_PREFIX)) {
                 const parsed = parseMountId(id.slice(1));
@@ -363,11 +378,33 @@ export function sdocsPlugin(userConfig) {
                 }
             }
             else if (entity.kind === 'PAGE') {
+                // The page body renders natively in the Explorer; only its
+                // [example] blocks are staged in iframes (with the project css),
+                // cascading block attributes over the content.docs stage defaults.
                 const rendered = await renderPageMarkdown(entity.body);
                 snippets[0].body = rendered.html;
-                snippets[0].stage = stageOf();
                 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) => {
+                    if (entry.examples[i]) {
+                        entry.examples[i].stage = {
+                            maxWidth: example.sizing.maxWidth ?? '100%',
+                            padding: example.sizing.padding ?? config.content.docs.padding,
+                            direction: example.sizing.direction ?? config.content.docs.direction,
+                            gap: example.sizing.gap ?? config.content.docs.gap,
+                            contentX: example.sizing.contentX ?? config.content.docs.contentX,
+                            contentY: example.sizing.contentY ?? config.content.docs.contentY,
+                        };
+                    }
+                });
+                for (const example of entry.examples) {
+                    example.highlightedHtml = await highlight(example.body);
+                }
             }
             else {
                 snippets[0].stage = stageOf();
@@ -396,16 +433,28 @@ export function sdocsPlugin(userConfig) {
             meta: e.meta,
             previews: e.previews.map((p) => ({ ...p, snippet: withUrl(e, p.snippet) })),
             examples: e.examples.map((s) => withUrl(e, s)),
-            content: e.content ? withUrl(e, e.content) : null,
+            // Page content renders natively (no iframe URL); see pageModules below.
+            content: e.content ? (e.kind === 'page' ? e.content : withUrl(e, e.content)) : null,
             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)
         const cssNames = config.css && typeof config.css === 'object'
             ? Object.keys(config.css)
             : [];
-        return `export const docs = ${JSON.stringify(data)};\nexport const cssNames = ${JSON.stringify(cssNames)};\nexport default docs;`;
+        // Native page components, as static dynamic imports so every mode (dev,
+        // embedded build, CLI build) code-splits them through the module graph —
+        // shared Svelte runtime, component CSS handled by Vite's import helper.
+        const pageImports = Array.from(docEntries.values())
+            .filter((e) => e.kind === 'page')
+            .map((e) => `\t${JSON.stringify(encodeEntityId(e.filePath, e.entitySlug))}: () => import(${JSON.stringify(pageVirtualId(e.filePath, e.entitySlug))}),`)
+            .join('\n');
+        return `export const docs = ${JSON.stringify(data)};\nexport const cssNames = ${JSON.stringify(cssNames)};\nexport const pageModules = {\n${pageImports}\n};\nexport default docs;`;
     }
     // ─── HMR helpers ───
     function invalidateVirtualModule(docFilePath) {
@@ -415,7 +464,7 @@ export function sdocsPlugin(userConfig) {
         if (mod) {
             server.moduleGraph.invalidateModule(mod);
         }
-        // Also invalidate iframe virtual modules for the changed doc file
+        // Also invalidate iframe and page virtual modules for the changed doc file
         if (docFilePath) {
             for (const entry of entriesOf(docFilePath)) {
                 for (const snippet of allSnippets(entry)) {
@@ -425,6 +474,12 @@ export function sdocsPlugin(userConfig) {
                         server.moduleGraph.invalidateModule(iframeMod);
                     }
                 }
+                if (entry.kind === 'page') {
+                    const pageMod = server.moduleGraph.getModuleById('\0' + pageVirtualId(docFilePath, entry.entitySlug));
+                    if (pageMod) {
+                        server.moduleGraph.invalidateModule(pageMod);
+                    }
+                }
             }
         }
         server.ws.send({ type: 'full-reload' });

package/package.json

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