@dominikcz/greg 0.9.29 → 0.9.31

package/docs/guide/asset-handling.md

@@ -18,6 +18,21 @@ Relative paths are resolved from the location of the `.md` file:
 ![diagram](./images/diagram.png)
 ```
 
+By default, Markdown images are rendered as thumbnails. Click an image to open
+the full-size preview.
+
+When preview is enabled, a caption is rendered under the thumbnail:
+- uses `title` when present,
+- otherwise falls back to `alt` text.
+
+You can disable this behavior globally in `greg.config.js`:
+
+```js
+export default {
+  markdownImagePreview: false,
+}
+```
+
 Absolute paths are resolved from the project root's `public/` directory:
 
 ```md

package/docs/guide/markdown/links-and-toc.md

@@ -62,3 +62,19 @@ Output:
 By default h2 and h3 headings are included. The right-side **Outline** panel is
 a persistent alternative. See `outline` prop in the
 [`<MarkdownDocs>` reference](/reference/markdowndocs).
+
+## Flex row list - `[[ ... ]]`
+
+Use `[[ ... ]]` to render multiple markdown blocks in a horizontal wrapping row.
+Each non-empty line inside the block becomes one flex item.
+
+```md
+[[
+![Freezer A](/know-how/gastro-orlen/mroznia/freezer-a.webp)
+![Freezer B](/know-how/gastro-orlen/mroznia/freezer-b.webp)
+![Freezer C](/know-how/gastro-orlen/mroznia/freezer-c.webp)
+]]
+```
+
+Use line breaks (Enter) to separate items. Brace syntax (`{...}`) and one-line
+comma-only syntax (for example `[[One, Two]]`) are not supported.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dominikcz/greg",
-  "version": "0.9.29",
+  "version": "0.9.31",
   "type": "module",
   "types": "./types/index.d.ts",
   "bin": {

package/src/lib/MarkdownDocs/MarkdownDocs.svelte

@@ -164,6 +164,8 @@
          * { id, title, titleHtml, sectionTitle, sectionTitleHtml?, sectionAnchor, excerptHtml, score }
          */
         searchProvider?: (query: string, limit?: number) => Promise<any[]>;
+        /** Render markdown images as thumbnails with click-to-preview overlay. */
+        markdownImagePreview?: boolean;
     };
 
     type VersionManifestEntry = {
@@ -209,6 +211,7 @@
             (gregConfig as any).outline ?? ([2, 3] as [number, number]),
         mermaidTheme = (gregConfig as any).mermaidTheme,
         mermaidThemes,
+        markdownImagePreview = (gregConfig as any).markdownImagePreview ?? true,
         breadcrumb = (gregConfig as any).breadcrumb ?? false,
         backToTop = (gregConfig as any).backToTop ?? false,
         lastModified: globalLastModified = (gregConfig as any).lastModified ?? false,
@@ -1733,6 +1736,7 @@
                             docsPrefix={withBase(currentSrcDir)}
                             {mermaidTheme}
                             {mermaidThemes}
+                            enableImagePreview={markdownImagePreview}
                             colorTheme={theme}
                         />
                         {#if lastModified && activeFrontmatter?._mtime}

package/src/lib/MarkdownDocs/MarkdownRenderer.svelte

@@ -203,6 +203,8 @@
          * When `'dark'`, automatically selects `mermaidTheme + '-dark'` if available.
          */
         colorTheme?: "light" | "dark";
+        /** Enable markdown image thumbnails + click-to-preview overlay. */
+        enableImagePreview?: boolean;
     };
     let {
         markdown,
@@ -211,6 +213,7 @@
         mermaidTheme = DEFAULT_MERMAID_THEME,
         mermaidThemes: extraThemes = {},
         colorTheme,
+        enableImagePreview = true,
     }: Props = $props();
 
     /** Combined theme map: built-ins overridden/extended by user-supplied themes. */
@@ -288,6 +291,19 @@
         };
     }
 
+    // ── Rehype plugin: markdown image component hydration ──────────────────────
+    // Replaces plain markdown <img> with <markdownimage> so runtime hydration can
+    // mount a Svelte component (thumbnail + modal + caption logic).
+    function rehypeMarkdownImageThumbs() {
+        return (tree: any) => {
+            if (!enableImagePreview) return;
+            visit(tree, "element", (node: any) => {
+                if (node.tagName !== "img") return;
+                node.tagName = "markdownimage";
+            });
+        };
+    }
+
     // ── Rehype plugin: shiki code blocks ─────────────────────────────────────────
 
     function rehypeShiki() {
@@ -421,6 +437,7 @@
             getRehypePluginEntries({
                 rehypeStepsWrapper,
                 rehypeMermaid,
+                rehypeMarkdownImageThumbs,
                 rehypeShiki,
             }),
         );
@@ -482,6 +499,9 @@
 </script>
 
 <!-- svelte-ignore a11y_no_static_element_interactions -->
-<div class="markdown-renderer markdown-body" bind:this={containerEl}>
+<div
+    class="markdown-renderer markdown-body"
+    bind:this={containerEl}
+>
     {@html html}
 </div>

package/src/lib/MarkdownDocs/__tests__/helpers.js

@@ -11,6 +11,7 @@ import rehypeAutolinkHeadings from 'rehype-autolink-headings';
 import rehypeCodeGroup from '../rehypeCodeGroup.js';
 import rehypeCodeTitle from '../rehypeCodeTitle.js';
 import { remarkContainers, rehypeContainers } from '../remarkContainers.js';
+import { remarkFlexRow } from '../remarkFlexRow.js';
 import { rehypeTocPlaceholder } from '../rehypeToc.js';
 import { remarkCodeMeta } from '../remarkCodeMeta.js';
 import { remarkImports } from '../remarkImports.js';
@@ -26,6 +27,7 @@ async function getProcessor(opts = {}) {
 	if (opts.containers || opts.toc || opts.imports) {
 		return unified()
 			.use(remarkParse)
+			.use(remarkFlexRow)
 			.use(remarkImports, opts.imports ?? defaultImportsOptions)
 			.use(remarkCodeMeta)
 			.use(remarkContainers, opts.containers ?? {})
@@ -41,6 +43,7 @@ async function getProcessor(opts = {}) {
 	if (!_processor) {
 		_processor = unified()
 			.use(remarkParse)
+			.use(remarkFlexRow)
 			.use(remarkImports, defaultImportsOptions)
 			.use(remarkCodeMeta)
 			.use(remarkContainers)

package/src/lib/MarkdownDocs/__tests__/markdown.test.js

@@ -147,6 +147,57 @@ describe('rehypeTocPlaceholder — [[TOC]]', () => {
 	});
 });
 
+describe('remarkFlexRow — [[ line\nline ]]', () => {
+	it('renders top-level flex container with wrapped items', async () => {
+		const html = await processMarkdown('[[\nOne\nTwo\nThree\n]]');
+		expect(html).toContain('class="markdown-flex-row"');
+		expect((html.match(/class="markdown-flex-item"/g) ?? []).length).toBe(3);
+		expect(html).toContain('>One<');
+		expect(html).toContain('>Two<');
+		expect(html).toContain('>Three<');
+	});
+
+	it('supports markdown content inside line items', async () => {
+		const html = await processMarkdown('[[\n**Bold**\n[Link](https://example.com)\n]]');
+		expect(html).toContain('<strong>Bold</strong>');
+		expect(html).toContain('<a href="https://example.com">Link</a>');
+	});
+
+	it('accepts newline-delimited items without commas', async () => {
+		const html = await processMarkdown('[[\nOne\nTwo\n]]');
+		expect(html).toContain('class="markdown-flex-row"');
+		expect((html.match(/class="markdown-flex-item"/g) ?? []).length).toBe(2);
+		expect(html).toContain('>One<');
+		expect(html).toContain('>Two<');
+	});
+
+	it('works inside list items', async () => {
+		const html = await processMarkdown('- [[\n  A\n  B\n  ]]');
+		expect(html).toContain('class="markdown-flex-row"');
+		expect((html.match(/class="markdown-flex-item"/g) ?? []).length).toBe(2);
+	});
+
+	it('supports image markdown inside items', async () => {
+		const html = await processMarkdown('[[\n![one](/one.png)\n![two](/two.png)\n]]');
+		expect(html).toContain('src="/one.png"');
+		expect(html).toContain('src="/two.png"');
+	});
+
+	it('supports multiline syntax with optional trailing commas', async () => {
+		const html = await processMarkdown('[[\n![one](/one.png),\n![two](/two.png)\n]]');
+		expect(html).toContain('class="markdown-flex-row"');
+		expect((html.match(/class="markdown-flex-item"/g) ?? []).length).toBe(2);
+		expect(html).toContain('src="/one.png"');
+		expect(html).toContain('src="/two.png"');
+	});
+
+	it('does not parse one-line comma-separated syntax', async () => {
+		const html = await processMarkdown('[[One, Two]]');
+		expect(html).not.toContain('class="markdown-flex-row"');
+		expect(html).toContain('[[One, Two]]');
+	});
+});
+
 // ─── Custom Containers ─────────────────────────────────────────────────────────
 
 describe('remarkContainers — ::: info', () => {

package/src/lib/MarkdownDocs/markdownRendererRuntime.ts

@@ -12,11 +12,13 @@ import rehypeCodeTitle from "./rehypeCodeTitle.js";
 import { remarkCodeMeta } from "./remarkCodeMeta.js";
 import { remarkCustomAnchors } from "./remarkCustomAnchors.js";
 import { remarkInlineAttrs } from "./remarkInlineAttrs.js";
+import { remarkFlexRow } from "./remarkFlexRow.js";
 import { remarkImportsBrowser } from "./remarkImportsBrowser.js";
 
 import Badge from "../components/Badge.svelte";
 import Button from "../components/Button.svelte";
 import Image from "../components/Image.svelte";
+import MarkdownImagePreview from "../components/MarkdownImagePreview.svelte";
 import Link from "../components/Link.svelte";
 import CodeGroup from "../components/CodeGroup.svelte";
 import Hero from "../components/Hero.svelte";
@@ -170,6 +172,10 @@ export const COMPONENT_REGISTRY: Record<string, ComponentHydrationEntry> = {
         component: Image,
         buildProps: buildPropsFromAttributes,
     },
+    markdownimage: {
+        component: MarkdownImagePreview,
+        buildProps: buildPropsFromAttributes,
+    },
     link: {
         component: Link,
         buildProps: buildPropsFromAttributes,
@@ -252,6 +258,7 @@ export function getRemarkPluginEntries(
     return [
         { name: "remark-parse", plugin: remarkParse },
         { name: "remark-gfm", plugin: remarkGfm },
+        { name: "remark-flex-row", plugin: remarkFlexRow },
         { name: "remark-inline-attrs", plugin: remarkInlineAttrs },
         {
             name: "remark-imports-browser",
@@ -278,6 +285,7 @@ export function getRemarkPluginEntries(
 export function getRehypePluginEntries(deps: {
     rehypeStepsWrapper: any;
     rehypeMermaid: any;
+    rehypeMarkdownImageThumbs: any;
     rehypeShiki: any;
 }): PluginEntry[] {
     return [
@@ -289,6 +297,10 @@ export function getRehypePluginEntries(deps: {
         },
         { name: "rehype-steps-wrapper", plugin: deps.rehypeStepsWrapper },
         { name: "rehype-mermaid", plugin: deps.rehypeMermaid },
+        {
+            name: "rehype-markdown-image-thumbs",
+            plugin: deps.rehypeMarkdownImageThumbs,
+        },
         { name: "rehype-shiki", plugin: deps.rehypeShiki },
         { name: "rehype-containers", plugin: rehypeContainers },
         { name: "rehype-code-group", plugin: rehypeCodeGroup },

package/src/lib/MarkdownDocs/remarkFlexRow.js

@@ -0,0 +1,86 @@
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkGfm from 'remark-gfm';
+import { visit } from 'unist-util-visit';
+
+function parseFlexPattern(value) {
+    const raw = String(value ?? '').trim();
+    if (!raw.startsWith('[[') || !raw.endsWith(']]')) return null;
+
+    const inner = raw.slice(2, -2).trim();
+    if (!inner) return [];
+    if (/^toc$/i.test(inner)) return null;
+
+    return parseLineItems(inner);
+}
+
+function parseLineItems(inner) {
+    if (!inner.includes('\n')) return null;
+
+    const parts = inner
+        .split('\n')
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((line) => line.replace(/,$/, '').trim())
+        .filter(Boolean);
+
+    return parts.length ? parts : null;
+}
+
+function parseMarkdownFragment(fragment, parser) {
+    const tree = parser.parse(fragment);
+    return Array.isArray(tree?.children) ? tree.children : [];
+}
+
+function createFlexItemNode(children) {
+    return {
+        type: 'flexRowItem',
+        data: {
+            hName: 'div',
+            hProperties: { className: ['markdown-flex-item'] },
+        },
+        children,
+    };
+}
+
+function createFlexRowNode(items, parser) {
+    return {
+        type: 'flexRowBlock',
+        data: {
+            hName: 'div',
+            hProperties: { className: ['markdown-flex-row'] },
+        },
+        children: items.map((item) =>
+            createFlexItemNode(parseMarkdownFragment(item, parser)),
+        ),
+    };
+}
+
+export function remarkFlexRow() {
+    const parser = unified().use(remarkParse).use(remarkGfm);
+
+    return (tree, file) => {
+        const source = typeof file?.value === 'string' ? file.value : '';
+
+        visit(tree, 'paragraph', (node, index, parent) => {
+            if (!parent || index == null) return;
+
+            let raw = '';
+            const start = node?.position?.start?.offset;
+            const end = node?.position?.end?.offset;
+
+            if (typeof start === 'number' && typeof end === 'number' && end >= start) {
+                raw = source.slice(start, end);
+            } else {
+                raw = (node.children ?? [])
+                    .map((child) => child?.value ?? '')
+                    .join('');
+            }
+
+            const parsedItems = parseFlexPattern(raw);
+            if (!parsedItems || parsedItems.length === 0) return;
+
+            parent.children[index] = createFlexRowNode(parsedItems, parser);
+        });
+    };
+}

package/src/lib/MarkdownDocs/vitePluginCopyDocs.js

@@ -1,7 +1,7 @@
 /**
  * vitePluginCopyDocs
  *
- * Copies docs/**\/*.md (and optional extra static dirs) to the build output
+ * Copies docs/** files (and optional extra static dirs) to the build output
  * directory as-is, so they can be fetched at runtime by the browser without
  * being compiled by mdsvex/rollup.
  *
@@ -10,7 +10,7 @@
  *
  * The `staticDirs` option (default: ['snippets']) lists additional project-root
  * directories whose files should also be served/copied verbatim.  This is
- * needed for `<<< @”‹/snippets/file.js` style snippet includes.
+ * needed for snippet include syntax that references files from static dirs.
  */
 
 import fs from 'node:fs';
@@ -25,11 +25,21 @@ export function vitePluginCopyDocs({ docsDir = 'docs', srcDir = '/docs', staticD
     let outDir = 'dist';
     let viteBase = '/';
 
+    function isTraversableDirectory(entry, fullPath) {
+        if (entry.isDirectory()) return true;
+        if (!entry.isSymbolicLink()) return false;
+        try {
+            return fs.statSync(fullPath).isDirectory();
+        } catch {
+            return false;
+        }
+    }
+
     function* walkAll(dir) {
         if (!fs.existsSync(dir)) return;
         for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
             const full = path.join(dir, entry.name);
-            if (entry.isDirectory()) {
+            if (isTraversableDirectory(entry, full)) {
                 yield* walkAll(full);
             } else if (entry.isFile()) {
                 yield full;
@@ -37,16 +47,29 @@ export function vitePluginCopyDocs({ docsDir = 'docs', srcDir = '/docs', staticD
         }
     }
 
-    function* walkMd(dir) {
-        for (const full of walkAll(dir)) {
-            if (full.endsWith('.md')) yield full;
-        }
-    }
-
     function toPosix(value) {
         return String(value).replace(/\\/g, '/');
     }
 
+    function getContentType(filePath) {
+        const ext = path.extname(filePath).toLowerCase();
+        switch (ext) {
+        case '.md': return 'text/plain; charset=utf-8';
+        case '.txt': return 'text/plain; charset=utf-8';
+        case '.json': return 'application/json; charset=utf-8';
+        case '.js': return 'text/javascript; charset=utf-8';
+        case '.css': return 'text/css; charset=utf-8';
+        case '.svg': return 'image/svg+xml';
+        case '.png': return 'image/png';
+        case '.jpg':
+        case '.jpeg': return 'image/jpeg';
+        case '.webp': return 'image/webp';
+        case '.gif': return 'image/gif';
+        case '.pdf': return 'application/pdf';
+        default: return 'application/octet-stream';
+        }
+    }
+
     function resolveRootPrefix() {
         const cleaned = trimSlashes(srcDir);
         return cleaned ? '/' + cleaned : '';
@@ -62,7 +85,7 @@ export function vitePluginCopyDocs({ docsDir = 'docs', srcDir = '/docs', staticD
         },
 
         /**
-         * In dev mode: serve .md files and staticDirs files as plain text.
+         * In dev mode: serve docs files and staticDirs files.
          * Vite doesn't auto-serve project files outside public/ as raw assets.
          */
         configureServer(server) {
@@ -86,17 +109,17 @@ export function vitePluginCopyDocs({ docsDir = 'docs', srcDir = '/docs', staticD
                     ? '/' + rawUrl.slice(base.length).replace(/^\/+/, '')
                     : rawUrl;
 
-                // Docs markdown files
-                const isDocsMarkdown = rootPrefix
-                    ? (url === rootPrefix || url.startsWith(rootPrefix + '/')) && url.endsWith('.md')
-                    : url.startsWith('/') && url.endsWith('.md');
-                if (isDocsMarkdown) {
+                // Docs files (markdown + local assets like images/pdf)
+                const isDocsPath = rootPrefix
+                    ? (url === rootPrefix || url.startsWith(rootPrefix + '/'))
+                    : url.startsWith('/');
+                if (isDocsPath) {
                     const rel = url.slice(rootPrefix.length).replace(/^\//, '');
                     for (const dir of (Array.isArray(docsDir) ? docsDir : [docsDir])) {
                         const filePath = path.resolve(root, dir, rel);
-                        if (fs.existsSync(filePath)) {
-                            res.setHeader('Content-Type', 'text/plain; charset=utf-8');
-                            res.end(fs.readFileSync(filePath, 'utf8'));
+                        if (fs.existsSync(filePath) && fs.statSync(filePath).isFile()) {
+                            res.setHeader('Content-Type', getContentType(filePath));
+                            res.end(fs.readFileSync(filePath));
                             return;
                         }
                     }
@@ -118,15 +141,15 @@ export function vitePluginCopyDocs({ docsDir = 'docs', srcDir = '/docs', staticD
             });
         },
 
-        /** After bundle is written, copy .md files and staticDirs verbatim. */
+        /** After bundle is written, copy docs files and staticDirs verbatim. */
         writeBundle() {
             let count = 0;
             const rootPrefix = trimSlashes(resolveRootPrefix());
 
-            // Copy markdown docs from all source dirs
+            // Copy docs files from all source dirs
             for (const dir of (Array.isArray(docsDir) ? docsDir : [docsDir])) {
                 const docsRoot = path.resolve(root, dir);
-                for (const srcFile of walkMd(docsRoot)) {
+                for (const srcFile of walkAll(docsRoot)) {
                     const rel = toPosix(path.relative(docsRoot, srcFile));
                     const destFile = path.join(outDir, rootPrefix, rel);
                     fs.mkdirSync(path.dirname(destFile), { recursive: true });

package/src/lib/MarkdownDocs/vitePluginFrontmatter.js

@@ -44,6 +44,16 @@ export function vitePluginFrontmatter({ docsDir = 'docs', srcDir = '/docs' } = {
         return cleaned ? `/${cleaned}` : '/';
     }
 
+    function isTraversableDirectory(entry, fullPath) {
+        if (entry.isDirectory()) return true;
+        if (!entry.isSymbolicLink()) return false;
+        try {
+            return fs.statSync(fullPath).isDirectory();
+        } catch {
+            return false;
+        }
+    }
+
     /** Collect all .md paths and return the virtual module source. */
     function buildModule() {
         const absDirs = (Array.isArray(docsDir) ? docsDir : [docsDir]).map(d => path.resolve(root, d));
@@ -56,7 +66,7 @@ export function vitePluginFrontmatter({ docsDir = 'docs', srcDir = '/docs' } = {
             catch { return; }
             for (const item of items) {
                 const full = path.join(dir, item.name);
-                if (item.isDirectory()) {
+                if (isTraversableDirectory(item, full)) {
                     walk(full, baseDir);
                 } else if (item.isFile() && item.name.endsWith('.md') && !item.name.startsWith('__')) {
                     const rel = path.relative(baseDir, full).replace(/\\/g, '/');

package/src/lib/components/MarkdownImagePreview.svelte

@@ -0,0 +1,345 @@
+<script lang="ts">
+    type Props = {
+        src?: string;
+        alt?: string;
+        title?: string;
+        width?: number | string;
+        height?: number | string;
+    };
+
+    let { src = "", alt = "", title = "", width, height }: Props = $props();
+
+    let isOpen = $state(false);
+    let zoom = $state(1);
+    let isDragging = $state(false);
+    let dragStartX = $state(0);
+    let dragStartY = $state(0);
+    let dragStartScrollLeft = $state(0);
+    let dragStartScrollTop = $state(0);
+    let viewportEl = $state<HTMLDivElement | null>(null);
+
+    const MIN_ZOOM = 1;
+    const MAX_ZOOM = 6;
+    const ZOOM_STEP = 0.25;
+
+    const caption = $derived((String(title || "").trim() || String(alt || "").trim()));
+    const zoomLabel = $derived(`${Math.round(zoom * 100)}%`);
+    const isPannable = $derived(zoom > 1);
+
+    const previewImageStyle = $derived.by(() => {
+        if (zoom <= 1) return undefined;
+        return `width: ${Math.round(zoom * 100)}%; max-width: none; max-height: none;`;
+    });
+
+    function clampZoom(value: number) {
+        return Math.max(MIN_ZOOM, Math.min(MAX_ZOOM, value));
+    }
+
+    function setZoom(value: number) {
+        zoom = clampZoom(value);
+    }
+
+    function zoomIn() {
+        setZoom(zoom + ZOOM_STEP);
+    }
+
+    function zoomOut() {
+        setZoom(zoom - ZOOM_STEP);
+    }
+
+    function resetZoom() {
+        setZoom(1);
+        isDragging = false;
+    }
+
+    function beginPan(event: MouseEvent) {
+        if (!isPannable || !viewportEl) return;
+        isDragging = true;
+        dragStartX = event.clientX;
+        dragStartY = event.clientY;
+        dragStartScrollLeft = viewportEl.scrollLeft;
+        dragStartScrollTop = viewportEl.scrollTop;
+        event.preventDefault();
+    }
+
+    function continuePan(event: MouseEvent) {
+        if (!isDragging || !viewportEl) return;
+        const deltaX = event.clientX - dragStartX;
+        const deltaY = event.clientY - dragStartY;
+        viewportEl.scrollLeft = dragStartScrollLeft - deltaX;
+        viewportEl.scrollTop = dragStartScrollTop - deltaY;
+        event.preventDefault();
+    }
+
+    function endPan() {
+        isDragging = false;
+    }
+
+    function openPreview() {
+        if (!src) return;
+        isOpen = true;
+        resetZoom();
+    }
+
+    function closePreview() {
+        isOpen = false;
+        resetZoom();
+    }
+
+    function handleKeydown(event: KeyboardEvent) {
+        if (event.key === "Escape" && isOpen) {
+            closePreview();
+        }
+    }
+
+    function handleWheel(event: WheelEvent) {
+        if (!isOpen) return;
+        event.preventDefault();
+        if (event.deltaY < 0) {
+            zoomIn();
+            return;
+        }
+        zoomOut();
+    }
+
+    $effect(() => {
+        if (typeof window === "undefined" || !isOpen) return;
+        window.addEventListener("keydown", handleKeydown);
+        return () => {
+            window.removeEventListener("keydown", handleKeydown);
+        };
+    });
+
+    $effect(() => {
+        if (typeof window === "undefined" || !isDragging) return;
+        window.addEventListener("mousemove", continuePan);
+        window.addEventListener("mouseup", endPan);
+        return () => {
+            window.removeEventListener("mousemove", continuePan);
+            window.removeEventListener("mouseup", endPan);
+        };
+    });
+</script>
+
+{#if src}
+    <figure class="markdown-image-figure">
+        <button
+            type="button"
+            class="markdown-image-thumb"
+            onclick={openPreview}
+            aria-label={caption ? `Open image preview: ${caption}` : "Open image preview"}
+        >
+            <img src={src} alt={alt} title={title || undefined} width={width} height={height} />
+        </button>
+        {#if caption}
+            <figcaption class="markdown-image-caption">{caption}</figcaption>
+        {/if}
+    </figure>
+{/if}
+
+{#if isOpen}
+    <div class="markdown-image-preview" role="dialog" aria-modal="true" aria-label="Image preview">
+        <button
+            type="button"
+            class="markdown-image-preview__backdrop"
+            aria-label="Close image preview"
+            onclick={closePreview}
+        ></button>
+        <div class="markdown-image-preview__content">
+            <div class="markdown-image-preview__toolbar" role="group" aria-label="Image zoom controls">
+                <button
+                    type="button"
+                    class="markdown-image-preview__zoom-btn"
+                    aria-label="Zoom out"
+                    onclick={zoomOut}
+                    disabled={zoom <= MIN_ZOOM}
+                >
+                    −
+                </button>
+                <button
+                    type="button"
+                    class="markdown-image-preview__zoom-btn markdown-image-preview__zoom-label"
+                    aria-label="Reset zoom"
+                    onclick={resetZoom}
+                >
+                    {zoomLabel}
+                </button>
+                <button
+                    type="button"
+                    class="markdown-image-preview__zoom-btn"
+                    aria-label="Zoom in"
+                    onclick={zoomIn}
+                    disabled={zoom >= MAX_ZOOM}
+                >
+                    +
+                </button>
+            </div>
+            <!-- svelte-ignore a11y_no_static_element_interactions -->
+            <div
+                class="markdown-image-preview__viewport"
+                class:is-pannable={isPannable}
+                class:is-dragging={isDragging}
+                bind:this={viewportEl}
+                onwheel={handleWheel}
+                onmousedown={beginPan}
+            >
+                <img
+                    src={src}
+                    alt={alt || caption || "Preview image"}
+                    class="markdown-image-preview__image"
+                    style={previewImageStyle}
+                />
+            </div>
+            <button
+                type="button"
+                class="markdown-image-preview__close"
+                aria-label="Close image preview"
+                onclick={closePreview}
+            >
+                ×
+            </button>
+            {#if caption}
+                <p class="markdown-image-preview__caption">{caption}</p>
+            {/if}
+        </div>
+    </div>
+{/if}
+
+<style>
+    .markdown-image-figure {
+        margin: 1rem 0;
+        max-width: 100%;
+    }
+
+    .markdown-image-thumb {
+        display: block;
+        padding: 0;
+        border: 0;
+        background: transparent;
+        cursor: zoom-in;
+        max-width: 100%;
+    }
+
+    .markdown-image-thumb img {
+        display: block;
+        max-width: 100%;
+        max-height: 220px;
+        width: auto;
+        border-radius: 8px;
+        border: 1px solid var(--greg-border-color);
+        transition: transform 0.14s ease, box-shadow 0.14s ease;
+    }
+
+    .markdown-image-thumb:hover img {
+        transform: translateY(-1px);
+        box-shadow: 0 8px 18px color-mix(in srgb, var(--greg-color) 16%, transparent);
+    }
+
+    .markdown-image-caption {
+        margin-top: 0.45rem;
+        font-size: 0.9rem;
+        color: var(--fgColor-muted);
+    }
+
+    .markdown-image-preview {
+        position: fixed;
+        inset: 0;
+        z-index: 1200;
+        display: grid;
+        place-items: center;
+        padding: 1.25rem;
+    }
+
+    .markdown-image-preview__backdrop {
+        position: absolute;
+        inset: 0;
+        border: none;
+        background: color-mix(in srgb, #000 74%, transparent);
+        cursor: zoom-out;
+    }
+
+    .markdown-image-preview__content {
+        position: relative;
+        max-width: min(92vw, 1500px);
+        max-height: 92vh;
+        z-index: 1;
+        display: grid;
+        gap: 0.5rem;
+    }
+
+    .markdown-image-preview__toolbar {
+        display: inline-flex;
+        gap: 0.4rem;
+        justify-self: center;
+    }
+
+    .markdown-image-preview__zoom-btn {
+        border: 1px solid rgb(255 255 255 / 0.4);
+        border-radius: 999px;
+        background: rgb(0 0 0 / 0.6);
+        color: #fff;
+        min-width: 2rem;
+        height: 2rem;
+        cursor: pointer;
+        font-size: 0.95rem;
+    }
+
+    .markdown-image-preview__zoom-btn:disabled {
+        opacity: 0.45;
+        cursor: not-allowed;
+    }
+
+    .markdown-image-preview__zoom-label {
+        padding: 0 0.7rem;
+        width: auto;
+        min-width: 4.25rem;
+    }
+
+    .markdown-image-preview__viewport {
+        overflow: auto;
+        max-width: min(92vw, 1500px);
+        max-height: 84vh;
+        padding: 0.15rem;
+        cursor: default;
+    }
+
+    .markdown-image-preview__viewport.is-pannable {
+        cursor: grab;
+    }
+
+    .markdown-image-preview__viewport.is-dragging {
+        cursor: grabbing;
+        user-select: none;
+    }
+
+    .markdown-image-preview__image {
+        display: block;
+        margin: 0 auto;
+        max-width: 100%;
+        max-height: 82vh;
+        border-radius: 0.625rem;
+        box-shadow: 0 18px 40px rgb(0 0 0 / 0.45);
+    }
+
+    .markdown-image-preview__close {
+        position: absolute;
+        top: -0.75rem;
+        right: -0.75rem;
+        width: 2rem;
+        height: 2rem;
+        border: 1px solid rgb(255 255 255 / 0.4);
+        border-radius: 999px;
+        background: rgb(0 0 0 / 0.6);
+        color: #fff;
+        line-height: 1;
+        cursor: pointer;
+    }
+
+    .markdown-image-preview__caption {
+        margin-top: 0.65rem;
+        margin-bottom: 0;
+        color: #fff;
+        text-align: center;
+        text-shadow: 0 1px 2px rgb(0 0 0 / 0.7);
+    }
+</style>

package/src/lib/scss/__markdown.scss

@@ -73,6 +73,27 @@
         margin: 1rem 0 0.4rem 0;
     }
 
+    .markdown-flex-row {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 0.75rem;
+        align-items: flex-start;
+        margin: 1rem 0;
+    }
+
+    .markdown-flex-item {
+        min-width: 0;
+        flex: 0 1 auto;
+    }
+
+    .markdown-flex-item > :first-child {
+        margin-top: 0;
+    }
+
+    .markdown-flex-item > :last-child {
+        margin-bottom: 0;
+    }
+
     img {
         max-width: 100%;
         border-style: none;

package/svelte.config.js

@@ -11,6 +11,7 @@ import { remarkImports } from './src/lib/MarkdownDocs/remarkImports.js';
 import { remarkGlobalComponents } from './src/lib/MarkdownDocs/remarkGlobalComponents.js';
 import { remarkCustomAnchors } from './src/lib/MarkdownDocs/remarkCustomAnchors.js';
 import { remarkInlineAttrs } from './src/lib/MarkdownDocs/remarkInlineAttrs.js';
+import { remarkFlexRow } from './src/lib/MarkdownDocs/remarkFlexRow.js';
 import { remarkEscapeSvelte } from './src/lib/MarkdownDocs/remarkEscapeSvelte.js';
 import { remarkMathToHtml } from './src/lib/MarkdownDocs/remarkMathToHtml.js';
 import { parseCodeDirectives, decorateHighlightedCodeHtml } from './src/lib/MarkdownDocs/codeDirectives.js';
@@ -103,6 +104,7 @@ const mdsvexOptions = {
 		},
 	},
 	remarkPlugins: [
+		remarkFlexRow,
 		remarkInlineAttrs,
 		remarkGlobalComponents,
 		remarkCodeMeta,

package/types/index.d.ts

@@ -342,6 +342,8 @@ export type GregConfig = {
     version?: string;
     /** Site title shown in the header. */
     mainTitle?: string;
+    /** Render markdown images as thumbnails with click-to-preview overlay. Default: true. */
+    markdownImagePreview?: boolean;
     /**
      * VitePress-compatible outline setting.
      *   false       – disable outline