Doc enhancements.

Author: dereuromark

README.md

@@ -103,6 +103,7 @@ https://sandbox.dereuromark.de/sandbox/djot
 - [Converters](docs/converters.md) - Markdown/BBCode to Djot conversion
 - [Cookbook](docs/cookbook.md) - Common customizations and recipes
 - [Architecture](docs/architecture.md) - Internal design
+- [Enhancements](docs/enhancements.md) - Fixes beyond the current spec
 
 ## Security
 

docs/cookbook.md

@@ -644,70 +644,110 @@ Output:
 
 ### Wiki Links
 
-Support `[[Page Name]]` and `[[Page Name|display text]]` wiki-style links:
+Support wiki-style links using a `wiki:` URL scheme. This approach uses standard
+djot link syntax and avoids ambiguity with nested spans (since `[[x]{.a}]{.b}` is valid djot).
 
 ```php
 use Djot\DjotConverter;
-use Djot\Node\Inline\Link;
-use Djot\Node\Inline\Text;
+use Djot\Event\RenderEvent;
 
 $converter = new DjotConverter();
-$parser = $converter->getParser()->getInlineParser();
 
-// Pattern matches [[target]] or [[target|display text]]
-$parser->addInlinePattern('/\[\[([^\]|]+)(?:\|([^\]]+))?\]\]/', function ($match, $groups, $p) {
-    $target = trim($groups[1]);
-    $display = isset($groups[2]) ? trim($groups[2]) : $target;
+// Handle wiki: scheme in links
+$converter->on('render.link', function (RenderEvent $event): void {
+    $link = $event->getNode();
+    $url = $link->getDestination() ?? '';
 
-    // Convert target to URL (customize as needed)
-    $url = '/wiki/' . rawurlencode(str_replace(' ', '-', $target));
+    if (str_starts_with($url, 'wiki:')) {
+        $target = substr($url, 5); // Remove 'wiki:' prefix
 
-    $link = new Link($url);
-    $link->appendChild(new Text($display));
-    $link->setAttribute('class', 'wikilink');
-    return $link;
+        // If empty, use the link text as target
+        if ($target === '') {
+            $text = '';
+            foreach ($link->getChildren() as $child) {
+                if ($child instanceof \Djot\Node\Inline\Text) {
+                    $text .= $child->getContent();
+                }
+            }
+            $target = $text;
+        }
+
+        // Convert to URL slug
+        $slug = strtolower(str_replace(' ', '-', $target));
+        $link->setDestination('/wiki/' . rawurlencode($slug));
+        $link->setAttribute('class', 'wikilink');
+    }
 });
 
-echo $converter->convert('See [[Home Page]] and [[API Reference|the API docs]].');
+echo $converter->convert('See [Home Page](wiki:) and [the API docs](wiki:API Reference).');
 ```
 
 Output:
 ```html
-<p>See <a href="/wiki/Home-Page" class="wikilink">Home Page</a> and <a href="/wiki/API-Reference" class="wikilink">the API docs</a>.</p>
+<p>See <a href="/wiki/home-page" class="wikilink">Home Page</a> and <a href="/wiki/api-reference" class="wikilink">the API docs</a>.</p>
 ```
 
+The syntax:
+- `[Page Name](wiki:)` - link text becomes the target
+- `[display text](wiki:Page Name)` - explicit target with custom display text
+
 #### Configurable Base URL
 
 ```php
-// Make the base URL configurable
 $wikiBaseUrl = '/docs/';  // or 'https://wiki.example.com/'
 
-$parser->addInlinePattern('/\[\[([^\]|]+)(?:\|([^\]]+))?\]\]/', function ($match, $groups, $p) use ($wikiBaseUrl) {
-    $target = trim($groups[1]);
-    $display = isset($groups[2]) ? trim($groups[2]) : $target;
-    $slug = strtolower(str_replace(' ', '-', $target));
+$converter->on('render.link', function (RenderEvent $event) use ($wikiBaseUrl): void {
+    $link = $event->getNode();
+    $url = $link->getDestination() ?? '';
 
-    $link = new Link($wikiBaseUrl . rawurlencode($slug));
-    $link->appendChild(new Text($display));
-    return $link;
+    if (str_starts_with($url, 'wiki:')) {
+        $target = substr($url, 5);
+
+        if ($target === '') {
+            $text = '';
+            foreach ($link->getChildren() as $child) {
+                if ($child instanceof \Djot\Node\Inline\Text) {
+                    $text .= $child->getContent();
+                }
+            }
+            $target = $text;
+        }
+
+        $slug = strtolower(str_replace(' ', '-', $target));
+        $link->setDestination($wikiBaseUrl . rawurlencode($slug));
+    }
 });
 ```
 
 #### With File Extension
 
 ```php
+use Djot\Event\RenderEvent;
+
 // Add .html extension for static sites
-$parser->addInlinePattern('/\[\[([^\]|]+)(?:\|([^\]]+))?\]\]/', function ($match, $groups, $p) {
-    $target = trim($groups[1]);
-    $display = isset($groups[2]) ? trim($groups[2]) : $target;
-    $slug = strtolower(str_replace(' ', '-', $target));
+$converter->on('render.link', function (RenderEvent $event): void {
+    $link = $event->getNode();
+    $url = $link->getDestination() ?? '';
 
-    $link = new Link('/pages/' . $slug . '.html');
-    $link->appendChild(new Text($display));
-    return $link;
+    if (str_starts_with($url, 'wiki:')) {
+        $target = substr($url, 5);
+
+        if ($target === '') {
+            $text = '';
+            foreach ($link->getChildren() as $child) {
+                if ($child instanceof \Djot\Node\Inline\Text) {
+                    $text .= $child->getContent();
+                }
+            }
+            $target = $text;
+        }
+
+        $slug = strtolower(str_replace(' ', '-', $target));
+        $link->setDestination('/pages/' . $slug . '.html');
+    }
 });
 
-// [[Installation Guide]] → <a href="/pages/installation-guide.html">Installation Guide</a>
+// [Installation Guide](wiki:) → <a href="/pages/installation-guide.html">Installation Guide</a>
 ```
 
 ### Hashtags
@@ -726,6 +766,59 @@ $parser->addInlinePattern('/#([a-zA-Z][a-zA-Z0-9_]*)/', function ($match, $group
 echo $converter->convert('Check out #PHP and #WebDev!');
 ```
 
+### Root-Relative Links
+
+Support `<~/path>` and `<~/path|display text>` for site-root-relative links:
+
+```php
+use Djot\DjotConverter;
+use Djot\Node\Inline\Link;
+use Djot\Node\Inline\Text;
+
+$converter = new DjotConverter();
+$parser = $converter->getParser()->getInlineParser();
+
+// Pattern matches <~/path> or <~/path|display text>
+$parser->addInlinePattern('/<~([^>|]+)(?:\|([^>]+))?>/​', function ($match, $groups, $p) {
+    $path = trim($groups[1]);
+    $display = isset($groups[2]) ? trim($groups[2]) : basename($path);
+
+    // Build root-relative URL
+    $url = '/' . ltrim($path, '/');
+
+    $link = new Link($url);
+    $link->appendChild(new Text($display));
+    $link->setAttribute('class', 'internal-link');
+    return $link;
+});
+
+echo $converter->convert('See <~/docs/installation> and <~/api/users|the API>.');
+```
+
+Output:
+```html
+<p>See <a href="/docs/installation" class="internal-link">installation</a> and <a href="/api/users" class="internal-link">the API</a>.</p>
+```
+
+#### Configurable Base Path
+
+```php
+$basePath = '/docs/v2';  // Prepend to all paths
+
+$parser->addInlinePattern('/<~([^>|]+)(?:\|([^>]+))?>/​', function ($match, $groups, $p) use ($basePath) {
+    $path = trim($groups[1]);
+    $display = isset($groups[2]) ? trim($groups[2]) : basename($path);
+
+    $url = $basePath . '/' . ltrim($path, '/');
+
+    $link = new Link($url);
+    $link->appendChild(new Text($display));
+    return $link;
+});
+
+// <~/guide> → <a href="/docs/v2/guide">guide</a>
+```
+
 ### Conditional Patterns
 
 Return `null` to fall back to default parsing: