feat(link-notes): add tooltip mode via link_snippet templates

Add a `link_snippet` option that switches a rule into "tooltip mode":
each matching link is replaced inline with the snippet rendered as a
template (${url}/${text}/${domain} substituted, HTML-escaped), producing
a pretty hover popup instead of a footnote. The rule's disclosure box is
emitted once per page rather than as per-link footnotes.

Because the replacement is inline HTML (not a footnote reference), tooltip
mode also works inside pipe-table cells, so links generated from CSVs by
the table-reader get the same popup. A referenced-but-missing link_snippet
fails the build, matching note_snippet behavior. Footnote mode is unchanged
and remains the default for rules without a link_snippet.

Adds 4 tests (345 total pass) and documents the new mode + placeholders.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Netdocs

docs-site/docs/plugins/link-notes.md

@@ -19,6 +19,16 @@ without you having to hand-add a footnote to every post. It is a first-party Net
     **alias**, and the legacy `programs` / `disclosure` config keys are still accepted — no
     changes are required to existing configs.
 
+## Two render modes: footnote or hover popup
+
+Each rule renders its note in one of two ways:
+
+- **Footnote mode** (default) — the link gets a small footnote marker; the note appears both as a
+  hover tooltip (with Material's `content.footnote.tooltips`) and once in the page's footnote list.
+- **Tooltip mode** (`link_snippet` set) — each matching link is *replaced inline* with a snippet
+  rendered as a template (a hover popup), and the rule's disclosure box is emitted **once per page**
+  instead of per-link footnotes. See [Pretty hover popups](#pretty-hover-popups-tooltip-mode) below.
+
 ## A common use-case: affiliate disclosures
 
 Attaching an affiliate-disclosure note to eBay Partner Network / tagged Amazon links means
@@ -89,6 +99,49 @@ When the snippet is a single **admonition** — the usual pretty affiliate box:
   a footnote, so the body is used directly there; the pretty box is reproduced for
   table-only links via the standalone admonition.)
 
+## Pretty hover popups (tooltip mode)
+
+Footnotes are great for a plain disclosure, but sometimes you want a *nicer* per-link popup — a
+styled card that appears on hover — instead of a superscript number and a footnote list. Point a
+rule at a **`link_snippet`** to switch it into tooltip mode:
+
+```json
+{
+  "name": "ebay",
+  "domains": [ "ebay.us" ],
+  "link_snippet": "snippets/ebay-link.html",
+  "note_snippet": "snippets/ebay-affiliate.md"
+}
+```
+
+In this mode, **every matching link is replaced inline** with `link_snippet` rendered as a template,
+and the `note_snippet` disclosure box is emitted **once at the bottom of the page** (no per-link
+footnotes at all). The snippet receives the matched link as template parameters, using the same
+`${key}` convention as parameterized [snippets](snippets.md) includes:
+
+| Placeholder | Value |
+|---|---|
+| `${url}` | The matched link URL (HTML-escaped). |
+| `${text}` | The link's display text (HTML-escaped). |
+| `${domain}` | The URL host, e.g. `ebay.us` (HTML-escaped). |
+
+A `link_snippet` is typically a small HTML fragment that wraps the link with a CSS-styled tooltip:
+
+```html
+<span class="affiliate-wrapper"><a href="${url}" target="_blank" rel="nofollow sponsored noopener"
+class="affiliate-link">${text}</a><span class="affiliate-tooltip"><span class="tooltip-title">eBay
+Affiliate Link</span><span class="tooltip-content">This is an eBay affiliate link…</span></span></span>
+```
+
+Because the replacement is inline HTML (not a footnote), tooltip mode also works **inside pipe-table
+cells** — where footnote references can't go — so links generated from CSVs by the
+[table-reader](table-reader.md) get the same pretty popup. A referenced-but-missing `link_snippet`
+**fails the build**, exactly like `note_snippet`.
+
+!!! tip "Style it once"
+    Put the tooltip CSS (`.affiliate-wrapper` / `.affiliate-tooltip` etc.) in your `extra_css` and
+    reuse the same classes across every affiliate snippet so all popups look consistent.
+
 ## How it works
 
 The plugin runs as a Markdown preprocessor (order `30`, after
@@ -173,14 +226,15 @@ Each **rule** object:
 | `name` | string | yes | Rule id; used to build the footnote label (`linknote-<name>`). |
 | `note` | string | yes* | Markdown shown as the tooltip and footer note. Legacy alias: `disclosure`. |
 | `note_snippet` | string | yes* | Path to a Markdown snippet whose content is used as the note (resolved against the project root / `docs` dir and their `snippets` subdirs). A single-admonition snippet contributes its title (→ `label`) and kind, and its body becomes the note. A referenced-but-missing snippet **fails the build**. Legacy alias: `disclosure_snippet`. |
+| `link_snippet` | string | no | Path to an HTML/Markdown snippet template. When set the rule switches to **tooltip mode**: each matching link is replaced inline with this snippet rendered with `${url}`/`${text}`/`${domain}` substituted, and the `note`/`note_snippet` box is emitted once per page (no footnotes). A referenced-but-missing snippet **fails the build**. |
 | `domains` | array | no† | Hosts that identify the link. Each entry is a domain string or `{ "domain": "...", "query_contains": "..." }`. Subdomains match automatically. |
 | `patterns` | array | no† | Regular expressions matched (case-insensitively) against the full URL. |
 | `query_contains` | string | no | Default substring a matching URL must contain (per-domain values override this). |
 | `label` | string | no | Title for the standalone fallback admonition (table-only links). Defaults to the snippet's admonition title, else `Links`. |
 
-\* A rule must provide the note text via either `note` or `note_snippet`. If `note_snippet`
-is set it takes precedence; a referenced snippet that cannot be found fails the build rather
-than falling back, so a mistyped path is caught instead of silently dropping the note.
+\* A rule must provide either a note (`note` or `note_snippet`) or a `link_snippet`. If `note_snippet`
+is set it takes precedence over `note`; any referenced snippet that cannot be found fails the build
+rather than falling back, so a mistyped path is caught instead of silently dropping the note.
 
 † A rule must provide at least one of `domains` or `patterns`.
 

src/Netdocs.Plugins/LinkNotesPlugin.cs

@@ -6,18 +6,22 @@
 namespace Netdocs.Plugins;
 
 /// <summary>
-/// Annotates outbound links that match configured rules with an automatic footnote
-/// reference. The footnote carries a note (arbitrary markdown), so:
+/// Annotates outbound links that match configured rules, so a note (arbitrary markdown) is
+/// attached to them automatically. Two render modes are supported per rule:
 /// <list type="bullet">
-///   <item>hovering the link shows the note as a tooltip (via
-///   <c>content.footnote.tooltips</c>), and</item>
-///   <item>the note is emitted once at the bottom of the page (the footnote list).</item>
+///   <item><b>Footnote mode</b> (default): the link gets a footnote reference whose definition is
+///   emitted once at the bottom of the page. With <c>content.footnote.tooltips</c> the note also
+///   shows on hover.</item>
+///   <item><b>Tooltip mode</b> (<c>link_snippet</c> set): each matching link is replaced inline
+///   with the snippet rendered as a template — the matched URL and link text are substituted for
+///   <c>${url}</c>/<c>${text}</c> — producing a hover popup, and the rule's disclosure box is
+///   emitted once per page instead of a footnote. Works inside pipe-table cells too.</item>
 /// </list>
 /// The plugin is generic and data-driven: each <em>rule</em> declares the domains
 /// (with an optional query marker) and/or regular expressions that identify its links,
-/// plus the note markdown. A common use-case is attaching affiliate-disclosure text to
-/// eBay Partner Network / tagged Amazon links (which also satisfies the once-per-page
-/// disclosure requirement automatically), but any note works.
+/// plus the note markdown and/or link snippet. A common use-case is attaching an
+/// affiliate-disclosure to eBay Partner Network / tagged Amazon links (which also satisfies the
+/// once-per-page disclosure requirement automatically), but any note works.
 /// <para>
 /// It runs after snippets/table-reader/macros so links injected by those plugins are
 /// covered. Registered as both <c>link-notes</c> and the legacy alias
@@ -28,7 +32,7 @@ namespace Netdocs.Plugins;
 public sealed partial class LinkNotesPlugin : IPlugin, IMarkdownPreprocessor
 {
     private sealed record DomainRule(string Domain, string? QueryContains);
-    private sealed record Rule(string Id, DomainRule[] Domains, Regex[] Patterns, string Note, string Label, string Kind);
+    private sealed record Rule(string Id, DomainRule[] Domains, Regex[] Patterns, string Note, string Label, string Kind, string? LinkSnippet);
 
     private readonly List<Rule> _rules = [];
     private readonly List<string> _snippetBasePaths = [];
@@ -122,14 +126,36 @@ public void Configure(IPluginContext ctx)
                     (kind, snippetTitle, note) = ExtractNote(content);
                 }
 
-                if (string.IsNullOrWhiteSpace(note))
+                // `link_snippet` opts the rule into *tooltip mode*: instead of appending a footnote,
+                // every matching link is replaced inline with this snippet rendered as a template
+                // (the matched URL and link text are substituted for `${url}`/`${text}`), producing a
+                // hover popup. This is the pretty per-link affiliate popup; a referenced-but-missing
+                // snippet fails the build for the same reason `note_snippet` does.
+                var linkSnippetPath = map.TryGetValue("link_snippet", out var lsp) ? lsp?.ToString() : null;
+                string? linkSnippet = null;
+                if (!string.IsNullOrWhiteSpace(linkSnippetPath))
                 {
-                    _log.LogWarning("link-notes: rule '{Id}' has no note (inline or snippet); skipping", id);
+                    linkSnippet = ReadSnippet(linkSnippetPath!);
+                    if (linkSnippet is null)
+                    {
+                        _configErrors.Add(
+                            $"rule '{id}' references link_snippet '{linkSnippetPath}' which was not found " +
+                            $"(searched: {string.Join(", ", _snippetBasePaths)})");
+                        continue;
+                    }
+                    linkSnippet = linkSnippet.Replace("\r\n", "\n").Trim('\n');
+                }
+
+                // A rule needs *something* to attach: either a note (footnote / page box) or a
+                // link_snippet (per-link popup). A rule with neither is a no-op.
+                if (string.IsNullOrWhiteSpace(note) && linkSnippet is null)
+                {
+                    _log.LogWarning("link-notes: rule '{Id}' has no note (inline or snippet) or link_snippet; skipping", id);
                     continue;
                 }
 
                 var label = explicitLabel ?? snippetTitle ?? "Links";
-                _rules.Add(new Rule(id!, domains, patterns, note!.Trim('\n'), label, kind));
+                _rules.Add(new Rule(id!, domains, patterns, note?.Trim('\n') ?? "", label, kind, linkSnippet));
             }
         }
 
@@ -200,6 +226,9 @@ public Task<string> ProcessAsync(Page page, string markdown, SiteContext site, C
         // (pipe-table cells), which need a standalone note block appended instead.
         var referenced = new HashSet<string>();
         var tableOnly = new HashSet<string>();
+        // Tooltip-mode rules (with a link_snippet) that matched at least one link on this page and so
+        // need their disclosure box emitted once at the bottom.
+        var boxed = new HashSet<string>();
 
         var lines = markdown.Split('\n');
         var inFence = false;
@@ -214,26 +243,19 @@ public Task<string> ProcessAsync(Page page, string markdown, SiteContext site, C
             }
             if (inFence) continue;
 
-            // Markdig does not reliably parse footnote references inside pipe-table cells, so injecting
-            // one there breaks the table. Detect matching links there (to guarantee the footer
-            // note) but don't annotate the link.
-            if (trimmed.StartsWith("|", StringComparison.Ordinal))
-            {
-                foreach (Match m in LinkRegex.Matches(lines[i]))
-                {
-                    var rule = MatchRule(m.Groups["url"].Value);
-                    if (rule is not null && !m.Groups["existing"].Success) tableOnly.Add(rule.Id);
-                }
-                continue;
-            }
-
-            lines[i] = LinkRegex.Replace(lines[i], m => AnnotateLink(m, referenced, tableOnly));
+            // Inside a pipe-table cell a footnote reference breaks the table (Markdig can't parse it
+            // there), but a tooltip-mode rule replaces the link with inline HTML, which is safe in a
+            // cell — so table rows are still processed; AnnotateLink is told it is in a table so a
+            // footnote-mode rule falls back to the standalone box instead of injecting a reference.
+            var inTable = trimmed.StartsWith("|", StringComparison.Ordinal);
+            lines[i] = LinkRegex.Replace(lines[i], m => AnnotateLink(m, referenced, tableOnly, boxed, inTable));
         }
 
         // A rule that got at least one inline reference doesn't also need a standalone block.
         tableOnly.ExceptWith(referenced);
 
-        if (referenced.Count == 0 && tableOnly.Count == 0) return Task.FromResult(markdown);
+        if (referenced.Count == 0 && tableOnly.Count == 0 && boxed.Count == 0)
+            return Task.FromResult(markdown);
 
         var sb = new StringBuilder(string.Join('\n', lines));
         sb.Append("\n\n");
@@ -248,25 +270,54 @@ public Task<string> ProcessAsync(Page page, string markdown, SiteContext site, C
         // Rules seen only inside tables get a standalone note admonition so the footer note
         // requirement is still met even though the individual links can't carry a tooltip.
         foreach (var rule in _rules.Where(r => tableOnly.Contains(r.Id)))
-        {
-            sb.Append("\n!!! ").Append(rule.Kind).Append(" \"").Append(rule.Label).Append("\"\n    ");
-            sb.Append(rule.Note.Replace("\n", "\n    ", StringComparison.Ordinal));
-            sb.Append('\n');
-        }
+            AppendBox(sb, rule);
+
+        // Tooltip-mode rules emit their disclosure admonition once per page (the per-link popups
+        // carry the hover text; this keeps a single always-visible disclosure without any footnotes).
+        foreach (var rule in _rules.Where(r => boxed.Contains(r.Id) && r.Note.Length > 0))
+            AppendBox(sb, rule);
 
         return Task.FromResult(sb.ToString());
     }
 
-    private string AnnotateLink(Match m, HashSet<string> referenced, HashSet<string> fallback)
+    // Appends a standalone `!!! kind "label"` admonition carrying a rule's note (indented body).
+    private static void AppendBox(StringBuilder sb, Rule rule)
+    {
+        sb.Append("\n!!! ").Append(rule.Kind).Append(" \"").Append(rule.Label).Append("\"\n    ");
+        sb.Append(rule.Note.Replace("\n", "\n    ", StringComparison.Ordinal));
+        sb.Append('\n');
+    }
+
+    private string AnnotateLink(Match m, HashSet<string> referenced, HashSet<string> fallback, HashSet<string> boxed, bool inTable)
     {
         var whole = m.Value;
         var rule = MatchRule(m.Groups["url"].Value);
         if (rule is null) return whole;
 
         // A footnote reference already follows this link (e.g. a hand-authored `[^ebay]`); leave it
-        // untouched so we don't produce duplicate references during content migration.
+        // untouched so we don't produce duplicate references / double-wrap during content migration.
         if (m.Groups["existing"].Success) return whole;
 
+        // Tooltip mode: replace the whole link with the link_snippet rendered as a template, passing
+        // the matched URL and link text. This works in table cells and next to adjacent links (it is
+        // inline HTML, not a footnote), and the disclosure box is emitted once per page.
+        if (rule.LinkSnippet is not null)
+        {
+            boxed.Add(rule.Id);
+            var text = ExtractLinkText(m.Groups["link"].Value);
+            var popup = RenderLinkSnippet(rule.LinkSnippet, m.Groups["url"].Value, text);
+            // Preserve any trailing attr-list the author added (rare, but keep it after the popup).
+            return popup + m.Groups["attr"].Value;
+        }
+
+        // Footnote mode inside a pipe-table cell: a reference would break the table, so record the
+        // rule for a standalone box instead of annotating the link.
+        if (inTable)
+        {
+            fallback.Add(rule.Id);
+            return whole;
+        }
+
         // Another link/reference is glued directly after this one (e.g. `[a](x)[b](y)`); a footnote
         // ref wedged between the `][` renders ambiguously, so skip it and rely on the fallback block.
         if (m.Groups["adjacent"].Success)
@@ -279,6 +330,42 @@ private string AnnotateLink(Match m, HashSet<string> referenced, HashSet<string>
         return whole + $"[^linknote-{rule.Id}]";
     }
 
+    // Extracts the display text of a markdown link `[text](url ...)` — everything between the first
+    // `[` and its matching `]`. Unescapes `\]` back to `]`.
+    private static string ExtractLinkText(string link)
+    {
+        var open = link.IndexOf('[');
+        if (open < 0) return "";
+        var i = open + 1;
+        var sb = new StringBuilder();
+        while (i < link.Length && link[i] != ']')
+        {
+            if (link[i] == '\\' && i + 1 < link.Length && link[i + 1] == ']') { sb.Append(']'); i += 2; continue; }
+            sb.Append(link[i]);
+            i++;
+        }
+        return sb.ToString();
+    }
+
+    // Renders a link_snippet template by substituting the matched URL / link text (HTML-escaped) for
+    // the `${url}`, `${text}` and `${domain}` placeholders — the same `${key}` convention the
+    // snippets plugin uses for parameterized includes.
+    private static string RenderLinkSnippet(string template, string url, string text)
+    {
+        var domain = Uri.TryCreate(url, UriKind.Absolute, out var uri) ? uri.Host : "";
+        return template
+            .Replace("${url}", HtmlEscape(url), StringComparison.Ordinal)
+            .Replace("${text}", HtmlEscape(text), StringComparison.Ordinal)
+            .Replace("${domain}", HtmlEscape(domain), StringComparison.Ordinal);
+    }
+
+    private static string HtmlEscape(string s) => s
+        .Replace("&", "&amp;", StringComparison.Ordinal)
+        .Replace("\"", "&quot;", StringComparison.Ordinal)
+        .Replace("<", "&lt;", StringComparison.Ordinal)
+        .Replace(">", "&gt;", StringComparison.Ordinal)
+        .Replace("'", "&#39;", StringComparison.Ordinal);
+
     private Rule? MatchRule(string url)
     {
         if (!Uri.TryCreate(url, UriKind.Absolute, out var uri)) return null;