sdocs 0.0.33 → 0.0.35

package/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.35] - 2026-07-03
+
+### Fixed
+
+- **The embedded Explorer guards its typography.** Host apps commonly style
+  bare `code`, `pre`, and `a` elements; those rules reached into the
+  Explorer's UI (shrinking code blocks, recoloring links). The Explorer now
+  pins its own font family, sizing, and link color at the `.sdocs-app`
+  boundary. Hosts with higher-specificity global rules should still scope
+  them away from `.sdocs-app`.
+
+## [0.0.34] - 2026-07-03
+
+### Fixed
+
+- **Preview paths are short and project-relative.** Preview URLs and emitted
+  file names used to encode the doc's absolute filesystem path, which leaked
+  the machine's directory layout into published sites and produced path
+  segments long enough for GitHub Pages to reject the deployment. Paths are
+  now encoded relative to the project root.
+
 ## [0.0.33] - 2026-07-03
 
 ### Added

package/dist/server/app-gen.js

@@ -5,7 +5,7 @@ import { dirname, resolve, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { discoverDocFiles, getSdocKind } from './discovery.js';
 import { extractSnippets, hasDefaultSnippet } from './snippet-extractor.js';
-import { base64urlEncode } from './snippet-compiler.js';
+import { encodeDocPath, setDocPathRoot } from './snippet-compiler.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 /** Source Explorer directory in the installed package (dist/explorer, next to dist/server) */
 function getExplorerSourceDir() {
@@ -174,6 +174,9 @@ export async function generateDevFiles(config, cwd) {
 /** Generate the staging directory with entry + preview HTML files for build mode */
 export async function generateBuildFiles(config, cwd) {
     const sdocsDir = await createStagingDir(cwd);
+    // The staging dir becomes the Vite root; encode doc paths against it now so
+    // these inputs match the URLs the plugin generates later.
+    setDocPathRoot(sdocsDir);
     // Copy Explorer components into the staging dir
     await copyExplorerApp(sdocsDir);
     await writeFile(resolve(sdocsDir, 'index.html'), generateIndexHtml(config.logo));
@@ -184,7 +187,7 @@ export async function generateBuildFiles(config, cwd) {
     // Discover snippets and generate preview HTML pages
     const docSnippets = await discoverSnippets(config, cwd);
     for (const { filePath, snippetNames } of docSnippets) {
-        const encoded = base64urlEncode(filePath);
+        const encoded = encodeDocPath(filePath);
         for (const snippetName of snippetNames) {
             const iframeId = `/@sdocs/iframe/${encoded}/${snippetName}.svelte`;
             const previewDir = resolve(sdocsDir, 'previews', encoded);

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

@@ -2,6 +2,10 @@
 export declare function base64urlEncode(str: string): string;
 /** Base64url decode */
 export declare function base64urlDecode(str: string): string;
+/** Set the root that doc paths are encoded against (the Vite root / staging dir) */
+export declare function setDocPathRoot(root: string): void;
+/** Encode a doc file path for use in URLs and emitted file names */
+export declare function encodeDocPath(filePath: string): string;
 /** Resolve relative imports to absolute paths for use in virtual components */
 export declare function resolveImportsToAbsolute(imports: string[], docFilePath: string): string[];
 /** Generate a virtual Svelte iframe wrapper component for a snippet.

package/dist/server/snippet-compiler.js

@@ -1,4 +1,4 @@
-import { dirname, resolve } from 'node:path';
+import { dirname, relative, resolve, sep } from 'node:path';
 /** Base64url encode a string (URL-safe, no padding) */
 export function base64urlEncode(str) {
     return Buffer.from(str).toString('base64url');
@@ -7,6 +7,22 @@ export function base64urlEncode(str) {
 export function base64urlDecode(str) {
     return Buffer.from(str, 'base64url').toString('utf-8');
 }
+// Doc paths are encoded relative to this root. Encoding absolute paths would
+// leak the machine's filesystem layout into published URLs and produce path
+// segments long enough to break static hosts (GitHub Pages rejects them).
+let docPathRoot = process.cwd();
+/** Set the root that doc paths are encoded against (the Vite root / staging dir) */
+export function setDocPathRoot(root) {
+    docPathRoot = root;
+}
+/** Encode a doc file path for use in URLs and emitted file names */
+export function encodeDocPath(filePath) {
+    return base64urlEncode(relative(docPathRoot, filePath).split(sep).join('/'));
+}
+/** Decode an encoded doc path back to an absolute path */
+function decodeDocPath(encoded) {
+    return resolve(docPathRoot, base64urlDecode(encoded));
+}
 /** Resolve relative imports to absolute paths for use in virtual components */
 export function resolveImportsToAbsolute(imports, docFilePath) {
     const docDir = dirname(docFilePath);
@@ -150,19 +166,19 @@ export function generateStaticPreviewHtml(scriptSrc, cssLinks) {
 }
 /** Build the virtual module ID for an iframe wrapper component */
 export function iframeVirtualId(docFilePath, snippetName) {
-    return `/@sdocs/iframe/${base64urlEncode(docFilePath)}/${snippetName}.svelte`;
+    return `/@sdocs/iframe/${encodeDocPath(docFilePath)}/${snippetName}.svelte`;
 }
 /** Build the preview URL for an iframe HTML page (dev mode) */
 export function previewUrl(docFilePath, snippetName) {
-    return `/@sdocs/preview/${base64urlEncode(docFilePath)}/${snippetName}`;
+    return `/@sdocs/preview/${encodeDocPath(docFilePath)}/${snippetName}`;
 }
 /** Build the preview URL for static build output */
 export function buildPreviewUrl(docFilePath, snippetName) {
-    return `/previews/${base64urlEncode(docFilePath)}/${snippetName}.html`;
+    return `/previews/${encodeDocPath(docFilePath)}/${snippetName}.html`;
 }
 /** Virtual module ID for a preview's mount script (embedded production builds) */
 export function mountVirtualId(docFilePath, snippetName) {
-    return `/@sdocs/mount/${base64urlEncode(docFilePath)}/${snippetName}.js`;
+    return `/@sdocs/mount/${encodeDocPath(docFilePath)}/${snippetName}.js`;
 }
 /** Parse a mount virtual ID back into its parts */
 export function parseMountId(id) {
@@ -170,7 +186,7 @@ export function parseMountId(id) {
     if (!match)
         return null;
     return {
-        docFilePath: base64urlDecode(match[1]),
+        docFilePath: decodeDocPath(match[1]),
         snippetName: match[2],
     };
 }
@@ -180,7 +196,7 @@ export function parseIframeId(id) {
     if (!match)
         return null;
     return {
-        docFilePath: base64urlDecode(match[1]),
+        docFilePath: decodeDocPath(match[1]),
         snippetName: match[2],
     };
 }
@@ -190,7 +206,7 @@ export function parsePreviewUrl(url) {
     if (!match)
         return null;
     return {
-        docFilePath: base64urlDecode(match[1]),
+        docFilePath: decodeDocPath(match[1]),
         snippetName: match[2],
     };
 }

package/dist/ui/styles/sdocs.css

@@ -13,6 +13,21 @@
 	color: var(--color-base-900);
 }
 
+/* Guard the Explorer's typography against host element rules when embedded:
+ * hosts commonly style bare `code`/`pre`/`a` (e.g. font-size: 0.875em), which
+ * would otherwise reach into the Explorer. Sizing stays wrapper-driven. */
+.sdocs-app code,
+.sdocs-app pre {
+	font-family: var(--mono);
+	font-size: inherit;
+	line-height: inherit;
+}
+
+.sdocs-app a {
+	color: inherit;
+	text-decoration: none;
+}
+
 .sdocs-app[data-sdocs-theme='dark'] {
 	/* base — layouts, backgrounds, surfaces, borders, text (inverted) */
 	--color-base-0: var(--color-zinc-1000);

package/dist/vite.js

@@ -6,7 +6,7 @@ import { parseComponent } from './server/prop-parser.js';
 import { extractSnippets, extractMarkupBody, hasDefaultSnippet, generateAutoDefault, } from './server/snippet-extractor.js';
 import { highlight, disposeHighlighter } from './server/highlighter.js';
 import { extractTocFromHtml } from './server/toc-extractor.js';
-import { parseIframeId, parseMountId, parsePreviewUrl, resolveImportsToAbsolute, generateIframeComponent, generateMountScript, generatePreviewHtml, generateStaticPreviewHtml, iframeVirtualId, mountVirtualId, previewUrl, buildPreviewUrl, base64urlEncode, } from './server/snippet-compiler.js';
+import { parseIframeId, parseMountId, parsePreviewUrl, resolveImportsToAbsolute, generateIframeComponent, generateMountScript, generatePreviewHtml, generateStaticPreviewHtml, iframeVirtualId, mountVirtualId, previewUrl, buildPreviewUrl, encodeDocPath, setDocPathRoot, } from './server/snippet-compiler.js';
 const VIRTUAL_MODULE_ID = 'virtual:sdocs';
 const RESOLVED_VIRTUAL_ID = '\0virtual:sdocs';
 const IFRAME_PREFIX = '/@sdocs/iframe/';
@@ -31,6 +31,7 @@ export function sdocsPlugin(userConfig) {
         name: 'sdocs',
         async configResolved(resolvedConfig) {
             root = resolvedConfig.root;
+            setDocPathRoot(root);
             isBuild = resolvedConfig.command === 'build';
             isSsrBuild = !!resolvedConfig.build?.ssr;
             base = resolvedConfig.base || '/';
@@ -158,7 +159,7 @@ export function sdocsPlugin(userConfig) {
                     }
                 }
                 for (const entry of docEntries.values()) {
-                    const encoded = base64urlEncode(entry.filePath);
+                    const encoded = encodeDocPath(entry.filePath);
                     for (const snippet of entry.snippets) {
                         const jsFileName = `previews/${encoded}/${snippet.name}.js`;
                         this.emitFile({

package/package.json

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