From 0dfbd08db6d7c7bd349c93360d5c791ff6700962 Mon Sep 17 00:00:00 2001
From: me <lorenz_2828@proton.me>
Date: Mon, 3 Aug 2026 02:13:10 +0200
Subject: [PATCH] feat: add Obsidian-style embeds and wiki-link display text

---
 README.md                              |   2 +
 docs/embeds.md                         |  86 ++++++++++++++++
 package.json                           |   2 +-
 src/parser/embeds.ts                   | 135 +++++++++++++++++++++++++
 src/parser/markdown.ts                 |   2 +
 src/parser/wiki-links.ts               |   9 +-
 static/markdown.css                    |  27 +++++
 tests/rendering/markdown-additional.md |  38 ++++++-
 tests/unit/embeds.ts                   | 116 +++++++++++++++++++++
 tests/unit/wiki-links.ts               |  34 +++++++
 10 files changed, 446 insertions(+), 5 deletions(-)
 create mode 100644 docs/embeds.md
 create mode 100644 src/parser/embeds.ts
 create mode 100644 tests/unit/embeds.ts
 create mode 100644 tests/unit/wiki-links.ts

diff --git a/README.md b/README.md
index 2955ab2a..cac4b1e5 100644
--- a/README.md
+++ b/README.md
@@ -50,6 +50,8 @@ issue](https://github.com/jannis-baum/vivify/issues/new/choose) or
 - links to other files: [relative links like in
   GitHub](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#relative-links)
   as well as absolute file links
+- [Obsidian-style embeds](docs/embeds.md) (`![[file]]`) and wiki-links
+  (`[[file]]`)
 - [add styles, classes, ids or other attributes directly from
   Markdown](https://github.com/arve0/markdown-it-attrs?tab=readme-ov-file#examples)
 - table of contents with `[[toc]]`
diff --git a/docs/embeds.md b/docs/embeds.md
new file mode 100644
index 00000000..7993b612
--- /dev/null
+++ b/docs/embeds.md
@@ -0,0 +1,86 @@
+# Embeds and wiki-links
+
+Vivify supports [Obsidian-style](https://help.obsidian.md/) wiki-links and
+embeds in addition to standard Markdown links.
+
+## Wiki-links
+
+With the syntax `[[page]]` you link to another file. If the link target has no
+file extension, a `.md` extension is assumed, matching Obsidian's behaviour:
+
+```md
+See [[other-note]], or [[other-note.md]] if you want an explicit extension.
+```
+
+To use custom link text, append a pipe and the desired text:
+
+```md
+[[other-note.md|My Other Note]]
+[[other-note|My Other Note]]
+```
+
+The left side is used for the link `href` (with `.md` appended when no
+extension is present), and the right side is shown as the link's text.
+
+## Embeds
+
+Prefixing a wiki-link with `!` turns it into an inline **embed** instead of a
+link:
+
+```md
+![[image.jpg]]
+```
+
+The path is resolved relative to the document you are viewing, just like regular
+relative links and images. Which HTML element is generated depends on the file
+type, detected from the file extension:
+
+- **Images** (`jpg`, `jpeg`, `png`, `gif`, `webp`, `svg`, `bmp`, `ico`, `avif`)
+  are embedded with an `<img>` element, just like a standard
+  `![](image.jpg)` reference.
+- **PDFs** (`pdf`) are embedded in an `<iframe>` rendered by the browser's
+  built-in PDF viewer.
+- **Videos** (`mp4`, `webm`, `ogv`, `mkv`, `mov`) are embedded with a
+  `<video controls>` player.
+- **Audio** (`mp3`, `wav`, `ogg`, `m4a`, `aac`, `flac`) is embedded with an
+  `<audio controls>` player.
+- **Any other file type** is also embedded in an `<iframe>`, so `![[note.md]]`
+  displays the rendered note inline.
+
+If the embed target has no file extension, a `.md` extension is appended
+before looking up the file, so `![[note]]` is equivalent to
+`![[note.md]]`.
+
+## Resizing embeds
+
+Append a pipe and a size after the path to control the dimensions of an embed.
+A width in pixels is supported, optionally combined with a height
+(`width x height`):
+
+```md
+![[image.jpg|300]]        <!-- 300 pixels wide -->
+![[image.jpg|300x200]]    <!-- 300 x 200 pixels -->
+```
+
+The same `|size` syntax works for videos, audio and iframes. An unparseable
+value (for example `![[image.jpg|large]]`) is ignored and the embed uses its
+default size.
+
+## Styling embeds
+
+Embeds use the following CSS classes, which you can override in your [custom
+styles](customization.md):
+
+- `.wiki-embed` — base class for all non-image embeds
+- `.wiki-embed-pdf` — PDFs
+- `.wiki-embed-iframe` — fallback iframes for other file types
+- `.wiki-embed-video` — `<video>` players
+- `.wiki-embed-audio` — `<audio>` players
+
+For example, to render PDFs at a different default height:
+
+```css
+.wiki-embed-pdf {
+    height: 800px;
+}
+```
diff --git a/package.json b/package.json
index 0fbc4ea4..d2ce3712 100644
--- a/package.json
+++ b/package.json
@@ -7,7 +7,7 @@
     "viv": "VIV_PORT=3000 node --import ./loader.mjs src/app.ts",
     "lint": "eslint src static",
     "lint-markdown": "markdownlint-cli2 --config .github/.markdownlint-cli2.yaml",
-    "test": "node --import ./loader.mjs --test tests/unit/cli.ts tests/unit/alerts.ts",
+    "test": "node --import ./loader.mjs --test tests/unit/cli.ts tests/unit/alerts.ts tests/unit/embeds.ts tests/unit/wiki-links.ts",
     "deduplicate": "yarn-deduplicate"
   },
   "type": "module",
diff --git a/src/parser/embeds.ts b/src/parser/embeds.ts
new file mode 100644
index 00000000..74f9cec2
--- /dev/null
+++ b/src/parser/embeds.ts
@@ -0,0 +1,135 @@
+import MarkdownIt from 'markdown-it';
+import { basename as pbasename, extname as pextname } from 'path';
+
+// Obsidian-style embeds use the `![[...]]` syntax to inline media files.
+// The path is treated as relative to the document being viewed, exactly like
+// regular wiki-links (`[[...]]`) and standard Markdown relative links, so the
+// browser resolves it through Vivify's `/viewer/<...>` route.
+
+const IMAGE_EXTS = new Set(['avif', 'bmp', 'gif', 'ico', 'jpeg', 'jpg', 'png', 'svg', 'webp']);
+const VIDEO_EXTS = new Set(['mkv', 'mov', 'mp4', 'ogv', 'webm']);
+const AUDIO_EXTS = new Set(['aac', 'flac', 'm4a', 'mp3', 'ogg', 'wav']);
+
+// Explicit MIME types for <source> fallbacks; omitted when unknown so the
+// browser infers from the file extension itself.
+const VIDEO_MIME: Record<string, string> = {
+    mkv: 'video/x-matroska',
+    mov: 'video/quicktime',
+    mp4: 'video/mp4',
+    ogv: 'video/ogg',
+    webm: 'video/webm',
+};
+const AUDIO_MIME: Record<string, string> = {
+    aac: 'audio/aac',
+    flac: 'audio/flac',
+    m4a: 'audio/mp4',
+    mp3: 'audio/mpeg',
+    ogg: 'audio/ogg',
+    wav: 'audio/wav',
+};
+
+// Escape a value for use inside a double-quoted HTML attribute.
+function escAttr(value: string): string {
+    return value.replace(/["&]/g, (char) => (char === '"' ? '&quot;' : '&amp;'));
+}
+
+function fileExtension(filePath: string): string {
+    return pextname(filePath).slice(1).toLowerCase();
+}
+
+// Split `![[content]]` inner content into `filePath | options`.
+function parseContent(content: string): { filePath: string; options: string } {
+    const pipe = content.indexOf('|');
+    if (pipe === -1) {
+        return { filePath: content.trim(), options: '' };
+    }
+    return {
+        filePath: content.slice(0, pipe).trim(),
+        options: content.slice(pipe + 1).trim(),
+    };
+}
+
+// Parse a size spec such as "300" (width) or "300x200" (width x height).
+function parseSize(options: string): { width?: string; height?: string } {
+    if (!options) return {};
+    const match = /^(\d+)(?:x(\d+))?$/.exec(options);
+    if (!match) return {};
+    return { width: match[1], height: match[2] ?? undefined };
+}
+
+function sizeAttrs(size: { width?: string; height?: string }): string {
+    let attrs = '';
+    if (size.width) attrs += ` width="${escAttr(size.width)}"`;
+    if (size.height) attrs += ` height="${escAttr(size.height)}"`;
+    return attrs;
+}
+
+function renderEmbedHtml(content: string): string {
+    const { filePath, options } = parseContent(content);
+    const src = escAttr(filePath);
+    const extn = fileExtension(filePath);
+    const sizing = sizeAttrs(parseSize(options));
+
+    // Image: inline like a regular Markdown image, honouring explicit sizing.
+    if (IMAGE_EXTS.has(extn)) {
+        const alt = escAttr(pbasename(filePath));
+        return `<img src="${src}" alt="${alt}"${sizing}>`;
+    }
+
+    // PDF: render inside the browser's native PDF viewer via an iframe.
+    if (extn === 'pdf') {
+        return `<iframe src="${src}" class="wiki-embed wiki-embed-pdf"${sizing} loading="lazy"></iframe>`;
+    }
+
+    // Video: <video> player with a <source> carrying the best known MIME type.
+    if (VIDEO_EXTS.has(extn)) {
+        const type = VIDEO_MIME[extn];
+        const typeAttr = type ? ` type="${type}"` : '';
+        return `<video controls class="wiki-embed wiki-embed-video"${sizing}><source src="${src}"${typeAttr}></video>`;
+    }
+
+    // Audio: <audio> player.
+    if (AUDIO_EXTS.has(extn)) {
+        const type = AUDIO_MIME[extn];
+        const typeAttr = type ? ` type="${type}"` : '';
+        return `<audio controls class="wiki-embed wiki-embed-audio"${sizing} src="${src}"${typeAttr}></audio>`;
+    }
+
+    // Fallback: any other file type is embedded in an iframe, so e.g. other
+    // Markdown notes get rendered through Vivify and displayed inline. When
+    // the path has no extension, assume it is a Markdown note and append `.md`
+    // so the viewer route serves it as rendered Markdown rather than raw.
+    if (!extn) {
+        return `<iframe src="${src}.md" class="wiki-embed wiki-embed-iframe"${sizing} loading="lazy"></iframe>`;
+    }
+    return `<iframe src="${src}" class="wiki-embed wiki-embed-iframe"${sizing} loading="lazy"></iframe>`;
+}
+
+export default function embeds(md: MarkdownIt): void {
+    md.inline.ruler.before('link', 'wiki_embed', (state, silent) => {
+        const max = state.posMax;
+        const start = state.pos;
+
+        // Look for opening `![[`
+        if (state.src.charCodeAt(start) !== 0x21 /* ! */) return false;
+        if (state.src.charCodeAt(start + 1) !== 0x5b /* [ */) return false;
+        if (state.src.charCodeAt(start + 2) !== 0x5b /* [ */) return false;
+
+        // Find closing `]]` (content may not contain a `]`, mirroring wiki-links)
+        let end = start + 3;
+        while (end < max && state.src.charCodeAt(end) !== 0x5d /* ] */) end++;
+        if (end + 1 >= max || state.src.charCodeAt(end + 1) !== 0x5d /* ] */) return false;
+        end += 2;
+
+        if (!silent) {
+            const content = state.src.slice(start + 3, end - 2);
+            // Emit the generated HTML as raw inline markup, the same technique
+            // `front-matter.ts` uses with `html_block` tokens.
+            const token = state.push('html_inline', '', 0);
+            token.content = renderEmbedHtml(content);
+        }
+
+        state.pos = end;
+        return true;
+    });
+}
diff --git a/src/parser/markdown.ts b/src/parser/markdown.ts
index cc526482..be3a099d 100644
--- a/src/parser/markdown.ts
+++ b/src/parser/markdown.ts
@@ -7,6 +7,7 @@ import highlight from './highlight.js';
 import graphviz from './dot.js';
 import mermaid from './mermaid.js';
 import wikiLinks from './wiki-links.js';
+import embeds from './embeds.js';
 import alerts from './alerts.js';
 import config from '../config.js';
 import { Renderer } from './parser.js';
@@ -77,6 +78,7 @@ mdit.use(graphviz);
 mdit.use(alerts);
 mdit.use(mermaid);
 mdit.use(wikiLinks);
+mdit.use(embeds);
 
 const renderMarkdown: Renderer = (content: string) => {
     return mdit.render(content);
diff --git a/src/parser/wiki-links.ts b/src/parser/wiki-links.ts
index da086365..318c60bc 100644
--- a/src/parser/wiki-links.ts
+++ b/src/parser/wiki-links.ts
@@ -18,14 +18,17 @@ export default function wikiLinkPlugin(md: MarkdownIt): void {
 
         if (!silent) {
             const content = state.src.slice(start + 2, end - 2);
-            const hasExtension = pbasename(content).indexOf('.') > -1;
-            const href = hasExtension ? content : content + '.md';
+            const pipe = content.indexOf('|');
+            const filePath = pipe === -1 ? content : content.slice(0, pipe).trim();
+            const displayText = pipe === -1 ? filePath : content.slice(pipe + 1).trim();
+            const hasExtension = pbasename(filePath).indexOf('.') > -1;
+            const href = hasExtension ? filePath : filePath + '.md';
 
             // Create link tokens
             const token = state.push('link_open', 'a', 1);
             token.attrSet('href', href);
 
-            state.push('text', '', 0).content = content;
+            state.push('text', '', 0).content = displayText;
             state.push('link_close', 'a', -1);
         }
 
diff --git a/static/markdown.css b/static/markdown.css
index bc6900d3..5afca957 100644
--- a/static/markdown.css
+++ b/static/markdown.css
@@ -223,6 +223,33 @@ h1, h2 {
 /* images */
 img, svg { max-width: 100%; }
 
+/* --------------------------------------------------------------------------
+ * WIKI-STYLE EMBEDS --------------------------------------------------------- */
+/* Obsidian-style embeds using the `![[...]]` syntax */
+.wiki-embed {
+    display: block;
+    margin: 0.5rem 0;
+}
+.wiki-embed.wiki-embed-pdf,
+.wiki-embed.wiki-embed-iframe {
+    width: 100%;
+    height: 600px;
+    border: 1px solid var(--border-regular);
+    border-radius: 6px;
+    overflow: hidden;
+}
+.wiki-embed.wiki-embed-iframe {
+    height: 500px;
+}
+.wiki-embed.wiki-embed-video {
+    width: 100%;
+    height: auto;
+    max-width: 100%;
+}
+.wiki-embed.wiki-embed-audio {
+    width: 100%;
+}
+
 /* keyboard */
 kbd {
     background-color: var(--bg-secondary);
diff --git a/tests/rendering/markdown-additional.md b/tests/rendering/markdown-additional.md
index f7c8476b..2552ff40 100644
--- a/tests/rendering/markdown-additional.md
+++ b/tests/rendering/markdown-additional.md
@@ -40,7 +40,43 @@ See basic syntax [here](markdown-basic.md), and extended syntax [here](markdown-
 
 With the syntax `[[relative-file]]` we can also link to other files with an
 implicit `.md`, e.g. to [[markdown-basic]], or also to any file with explicit
-extensions like [[markdown-basic.md]]
+extensions like [[markdown-basic.md]]. Custom display text can be specified
+after a pipe: [[markdown-basic|Basic Syntax]].
+
+### Embeds
+
+With a leading `!` the wiki-link syntax `![[...]]` turns a link into an inline
+embed instead, similar to [Obsidian](https://help.obsidian.md/). The path is
+relative to the current document, just like regular relative links.
+
+Images are embedded inline and can be resized by specifying a width (or
+`width x height`) after a pipe:
+
+![[photo.jpg]]
+
+![[photo.png|300]]
+
+![[photo.gif|300x200]]
+
+PDFs are embedded in an `iframe` rendered by the browser's built-in PDF viewer:
+
+![[document.pdf]]
+
+Videos and audio use the respective HTML `<video>` / `<audio>` players:
+
+![[clip.mp4]]
+
+![[clip.webm|640]]
+
+![[podcast.mp3]]
+
+An embed without a file extension resolves to Markdown:
+
+![[notes]]
+
+Any other file type is also embedded in an `iframe`:
+
+![[notes.md]]
 
 ## Math
 
diff --git a/tests/unit/embeds.ts b/tests/unit/embeds.ts
new file mode 100644
index 00000000..b0707faa
--- /dev/null
+++ b/tests/unit/embeds.ts
@@ -0,0 +1,116 @@
+import assert from 'node:assert';
+import test, { describe } from 'node:test';
+import MarkdownIt from 'markdown-it';
+import embeds from '../../src/parser/embeds.js';
+
+// A MarkdownIt instance with just the embeds plugin (mirroring how it is
+// registered in `parser/markdown.ts`) for focused unit testing.
+const md = new MarkdownIt({ html: true });
+md.use(embeds);
+
+const render = (input: string): string => md.render(input);
+
+describe('Embeds: ![[...]]', () => {
+    test('embeds an image', () => {
+        assert.strictEqual(
+            render('![[image.jpg]]'),
+            '<p><img src="image.jpg" alt="image.jpg"></p>\n',
+        );
+    });
+
+    test('embeds an image with a relative path', () => {
+        assert.strictEqual(
+            render('![[photos/image.png]]'),
+            '<p><img src="photos/image.png" alt="image.png"></p>\n',
+        );
+    });
+
+    test('supports resizing images with a width', () => {
+        assert.strictEqual(
+            render('![[image.jpg|300]]'),
+            '<p><img src="image.jpg" alt="image.jpg" width="300"></p>\n',
+        );
+    });
+
+    test('supports resizing images with width x height', () => {
+        assert.strictEqual(
+            render('![[image.jpg|300x200]]'),
+            '<p><img src="image.jpg" alt="image.jpg" width="300" height="200"></p>\n',
+        );
+    });
+
+    test('does not interfere with standard Markdown images', () => {
+        assert.strictEqual(
+            render('![alt text](image.jpg)'),
+            '<p><img src="image.jpg" alt="alt text"></p>\n',
+        );
+        assert.strictEqual(render('![](image.jpg)'), '<p><img src="image.jpg" alt=""></p>\n');
+    });
+
+    test('embeds a PDF in an iframe', () => {
+        assert.strictEqual(
+            render('![[document.pdf]]'),
+            '<p><iframe src="document.pdf" class="wiki-embed wiki-embed-pdf" loading="lazy"></iframe></p>\n',
+        );
+    });
+
+    test('embeds a video', () => {
+        assert.strictEqual(
+            render('![[clip.mp4]]'),
+            '<p><video controls class="wiki-embed wiki-embed-video"><source src="clip.mp4" type="video/mp4"></video></p>\n',
+        );
+    });
+
+    test('embeds an audio file', () => {
+        assert.strictEqual(
+            render('![[song.mp3]]'),
+            '<p><audio controls class="wiki-embed wiki-embed-audio" src="song.mp3" type="audio/mpeg"></audio></p>\n',
+        );
+    });
+
+    test('applies sizing to a video player', () => {
+        assert.strictEqual(
+            render('![[clip.mp4|320]]'),
+            '<p><video controls class="wiki-embed wiki-embed-video" width="320"><source src="clip.mp4" type="video/mp4"></video></p>\n',
+        );
+    });
+
+    test('applies sizing to an audio player', () => {
+        assert.strictEqual(
+            render('![[song.mp3|400x80]]'),
+            '<p><audio controls class="wiki-embed wiki-embed-audio" width="400" height="80" src="song.mp3" type="audio/mpeg"></audio></p>\n',
+        );
+    });
+
+    test('falls back to an iframe for unknown file types', () => {
+        assert.strictEqual(
+            render('![[archive.zip]]'),
+            '<p><iframe src="archive.zip" class="wiki-embed wiki-embed-iframe" loading="lazy"></iframe></p>\n',
+        );
+    });
+
+    test('appends .md when no extension is given (markdown embed)', () => {
+        assert.strictEqual(
+            render('![[note]]'),
+            '<p><iframe src="note.md" class="wiki-embed wiki-embed-iframe" loading="lazy"></iframe></p>\n',
+        );
+    });
+
+    test('renders an embed inline within a paragraph', () => {
+        assert.strictEqual(
+            render('See ![[image.jpg]].'),
+            '<p>See <img src="image.jpg" alt="image.jpg">.</p>\n',
+        );
+    });
+
+    test('leaves a lone exclamation mark untouched', () => {
+        assert.strictEqual(render('Hello!'), '<p>Hello!</p>\n');
+    });
+
+    test('treats an invalid size spec as no sizing', () => {
+        assert.strictEqual(
+            render('![[image.jpg|nope]]'),
+            '<p><img src="image.jpg" alt="image.jpg"></p>\n',
+        );
+    });
+});
diff --git a/tests/unit/wiki-links.ts b/tests/unit/wiki-links.ts
new file mode 100644
index 00000000..add953ce
--- /dev/null
+++ b/tests/unit/wiki-links.ts
@@ -0,0 +1,34 @@
+import assert from 'node:assert';
+import test, { describe } from 'node:test';
+import MarkdownIt from 'markdown-it';
+import wikiLinkPlugin from '../../src/parser/wiki-links.js';
+
+const md = new MarkdownIt({ html: true });
+md.use(wikiLinkPlugin);
+
+const render = (input: string): string => md.render(input);
+
+describe('Wiki-links: [[...]]', () => {
+    test('renders a wiki-link to a Markdown file', () => {
+        assert.strictEqual(render('[[note.md]]'), '<p><a href="note.md">note.md</a></p>\n');
+    });
+
+    test('appends .md when no extension is given', () => {
+        assert.strictEqual(render('[[note]]'), '<p><a href="note.md">note</a></p>\n');
+    });
+
+    test('supports custom display text after a pipe', () => {
+        assert.strictEqual(render('[[note.md|My Note]]'), '<p><a href="note.md">My Note</a></p>\n');
+    });
+
+    test('applies .md extension when no extension and custom text are given', () => {
+        assert.strictEqual(render('[[note|My Note]]'), '<p><a href="note.md">My Note</a></p>\n');
+    });
+
+    test('handles paths with subdirectories', () => {
+        assert.strictEqual(
+            render('[[posts/hello.md]]'),
+            '<p><a href="posts/hello.md">posts/hello.md</a></p>\n',
+        );
+    });
+});