sdocs 0.0.50 → 0.0.52

package/CHANGELOG.md

@@ -7,6 +7,47 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- **The sdoc grammar colors `[PAGE]` bodies as markdown.** Headings, bold,
+  lists, and fences highlight in page prose (the body's block indent is
+  accounted for, so indented bodies don't read as code blocks). Applies
+  everywhere the grammar is used — the VS Code extension and ` ```sdoc `
+  fences on the site.
+
+### Fixed
+
+- **Page expressions with string literals no longer break the page.** The
+  markdown pass HTML-escaped quotes (and `&&`, `<`) inside `{…}` expressions,
+  so `{@render colorBox("#ff0000")}` or `{format("x")}` in a `[PAGE]` body
+  failed to compile. Balanced `{…}` spans now pass through verbatim; prose
+  around them escapes exactly as before, and code fences and inline code stay
+  inert.
+
+### Added
+
+- **`\{` escapes a literal brace in page prose.** Previously a lone brace
+  written in prose could break the page; a backslash-escaped brace now renders
+  as an inert literal `{`.
+
 ## [0.0.50] - 2026-07-05
 
 ### Fixed

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"
@@ -229,15 +241,92 @@
 			"patterns": [
 				{
 					"begin": "(^|\\G)",
-					"while": "(^|\\G)(?!\\s*\\[/PAGE\\]\\s*$)",
+					"while": "(^|\\G)(?!\\s*\\[/PAGE\\]\\s*$)(?:\\t|[ ]{1,4})?",
+					"contentName": "meta.embedded.block.markdown",
 					"patterns": [
 						{
-							"include": "source.svelte"
+							"include": "#page-svelte-block"
+						},
+						{
+							"include": "text.html.markdown"
 						}
 					]
 				}
 			]
 		},
+		"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 { 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';

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/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()
@@ -27,6 +28,55 @@ function escapeHtml(text) {
         .replace(/>/g, '>')
         .replace(/"/g, '"');
 }
+/** marked-equivalent prose escaping (entities already present survive). */
+function escapeProse(text) {
+    return text
+        .replace(/&(?!(?:#\d{1,7}|#[Xx][a-fA-F0-9]{1,6}|\w+);)/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+/** Index of the `}` closing the `{` at `open`, or -1. Skips quoted strings. */
+function findExpressionEnd(text, open) {
+    let depth = 0;
+    for (let i = open; i < text.length; i++) {
+        const ch = text[i];
+        if (ch === '"' || ch === "'" || ch === '`') {
+            for (i++; i < text.length && text[i] !== ch; i++) {
+                if (text[i] === '\\')
+                    i++;
+            }
+            if (i >= text.length)
+                return -1;
+        }
+        else if (ch === '{')
+            depth++;
+        else if (ch === '}' && --depth === 0)
+            return i;
+    }
+    return -1;
+}
+/**
+ * Escape prose while passing balanced `{…}` spans through verbatim, so Svelte
+ * expressions survive the markdown pass — string literals, `&&`, comparisons.
+ * An unmatched `{` falls back to prose escaping, exactly as before.
+ */
+function escapeTextKeepingExpressions(text) {
+    let out = '';
+    let from = 0;
+    for (let i = 0; i < text.length; i++) {
+        if (text[i] !== '{')
+            continue;
+        const end = findExpressionEnd(text, i);
+        if (end === -1)
+            break;
+        out += escapeProse(text.slice(from, i)) + text.slice(i, end + 1);
+        from = end + 1;
+        i = end;
+    }
+    return out + escapeProse(text.slice(from));
+}
 function plainText(tokens) {
     let out = '';
     for (const token of tokens) {
@@ -37,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 });
@@ -97,8 +166,20 @@ export async function renderPageMarkdown(source) {
             // tags, {expressions} stay expressions.
             html(token) {
                 return token.text;
+            },
+            // Prose escapes for HTML, but balanced {…} spans stay verbatim so
+            // expressions keep their quotes and operators. A backslash-escaped
+            // brace (`\{`) becomes an inert literal brace.
+            text(token) {
+                if (token.type === 'escape')
+                    return escapeBraces(escapeProse(token.text));
+                if ('tokens' in token && token.tokens)
+                    return this.parser.parseInline(token.tokens);
+                if ('escaped' in token && token.escaped)
+                    return token.text;
+                return escapeTextKeepingExpressions(token.text);
             }
         }
     });
-    return { html: marked.parser(tokens), toc };
+    return marked.parser(tokens);
 }

package/package.json

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