feat(link-notes): support note_snippet for reusable affiliate notes

Netdocs · Copilot · Netdocs · commit 901307fd09ee · 2026-07-27T13:03:39.000-05:00
Rules can now source their note from a Markdown snippet via `note_snippet`
(legacy alias `disclosure_snippet`) instead of duplicating the text inline
in config. Paths resolve against the project root and docs dir plus their
conventional `snippets` subdirectories.

When the snippet is a single admonition (the typical pretty affiliate box),
the plugin extracts its title (used as the standalone fallback box label
unless a `label` is set) and kind, and uses its de-indented body as the
note. An admonition cannot render inside a footnote definition, so the body
is used directly for the tooltip/footer note while the box is reproduced for
table-only links.

Also fixes multi-line footnote definitions to indent continuation lines so
multi-paragraph notes stay within the footnote.

Co-authored-by: Copilot &lt;223556219+Copilot@users.noreply.github.com&gt;
diff --git a/docs-site/docs/plugins/link-notes.md b/docs-site/docs/plugins/link-notes.md
@@ -51,6 +51,44 @@ page's footnote list.
     posts readable and avoids per-link markup such as
     `--8<-- "ebay.html" text="..." url="..."`, which is noisier and easy to get wrong.
 
+## Reusing a snippet for the note
+
+Instead of typing the note text inline in your config, a rule can point at a Markdown
+**snippet file** with `note_snippet`. This keeps a single source of truth for a disclosure
+that you may also include manually elsewhere (via [snippets](snippets.md)), so the wording
+stays consistent everywhere:
+
+```json
+{
+  "name": "ebay",
+  "domains": [ "ebay.us" ],
+  "note_snippet": "snippets/ebay-affiliate.md"
+}
+```
+
+The path is resolved against the project root and the `docs/` directory, each with a
+conventional `snippets` subdirectory — so `snippets/ebay-affiliate.md`,
+`docs/snippets/ebay-affiliate.md`, or a bare `ebay-affiliate.md` (found in `docs/snippets`)
+all work. If the snippet can't be found, the plugin logs a warning and falls back to the
+inline `note` (when one is set).
+
+When the snippet is a single **admonition** — the usual pretty affiliate box:
+
+```markdown
+!!! info "E-Bay Affiliate Links Used"
+    This post **DOES** include eBay affiliate links. ...
+
+    You will pay the same amount as normal ...
+```
+
+…the plugin is admonition-aware:
+
+- its **title** (`E-Bay Affiliate Links Used`) becomes the standalone fallback box's header
+  (unless the rule sets an explicit `label`), and its admonition **kind** (`info`) is reused;
+- its **body** becomes the tooltip / footer-note text. (An admonition can't render *inside*
+  a footnote, so the body is used directly there; the pretty box is reproduced for
+  table-only links via the standalone admonition.)
+
 ## How it works
 
 The plugin runs as a Markdown preprocessor (order `30`, after
@@ -133,13 +171,17 @@ Each **rule** object:
 | Field | Type | Required | Description |
 |---|---|---|---|
 | `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`. |
-| `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. |
+| `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. Legacy alias: `disclosure_snippet`. |
+| `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). Default `Links`. |
+| `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 both are set and
+the snippet resolves, the snippet wins; otherwise `note` is the fallback).
 
-\* A rule must provide at least one of `domains` or `patterns`.
+† A rule must provide at least one of `domains` or `patterns`.
 
 !!! tip
     Enable [`content.footnote.tooltips`](../reference/theme.md) in your theme `features`
diff --git a/src/Netdocs.Plugins/LinkNotesPlugin.cs b/src/Netdocs.Plugins/LinkNotesPlugin.cs
@@ -25,12 +25,13 @@ namespace Netdocs.Plugins;
 /// still accepted.
 /// </para>
 /// </summary>
-public sealed class LinkNotesPlugin : IPlugin, IMarkdownPreprocessor
+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);
+    private sealed record Rule(string Id, DomainRule[] Domains, Regex[] Patterns, string Note, string Label, string Kind);
 
     private readonly List<Rule> _rules = [];
+    private readonly List<string> _snippetBasePaths = [];
     private ILogger? _log;
 
     public string Name => "link-notes";
@@ -49,6 +50,16 @@ public void Configure(IPluginContext ctx)
     {
         _log = ctx.Logger;
 
+        // Snippet search roots (mirrors SnippetsPlugin): the project root and docs dir, each with a
+        // conventional `snippets` subdirectory. A `note_snippet` path is resolved against these so a
+        // rule can reuse the same admonition snippet included elsewhere on the site.
+        var root = ctx.Config.ProjectRoot ?? "";
+        void AddBase(string p) { if (p.Length > 0 && !_snippetBasePaths.Contains(p)) _snippetBasePaths.Add(p); }
+        AddBase(Path.GetFullPath(root.Length == 0 ? "." : root));
+        AddBase(Path.GetFullPath(Path.Combine(root, "snippets")));
+        AddBase(Path.GetFullPath(ctx.Config.AbsoluteDocsDir));
+        AddBase(Path.GetFullPath(Path.Combine(ctx.Config.AbsoluteDocsDir, "snippets")));
+
         // Accept the new `rules` key; fall back to the legacy `programs` key (affiliate-links).
         if (!ctx.PluginOptions.TryGetValue("rules", out var raw) || raw is not IEnumerable<object?>)
             ctx.PluginOptions.TryGetValue("programs", out raw);
@@ -60,10 +71,11 @@ public void Configure(IPluginContext ctx)
                 if (item is not IReadOnlyDictionary<string, object?> map) continue;
 
                 var id = map.TryGetValue("name", out var n) ? n?.ToString() : null;
-                // `note` (new) or `disclosure` (legacy alias).
+                if (string.IsNullOrWhiteSpace(id)) continue;
+
+                // `note` (new) or `disclosure` (legacy alias) supply the note markdown inline.
                 var note = (map.TryGetValue("note", out var nt) ? nt?.ToString() : null)
                          ?? (map.TryGetValue("disclosure", out var d) ? d?.ToString() : null);
-                if (string.IsNullOrWhiteSpace(id) || string.IsNullOrWhiteSpace(note)) continue;
 
                 // Rule-level query marker is the default for any domain that doesn't override it.
                 var defaultQuery = map.TryGetValue("query_contains", out var q) ? q?.ToString() : null;
@@ -77,19 +89,89 @@ public void Configure(IPluginContext ctx)
                     continue;
                 }
 
-                // Title used for the standalone fallback admonition (table-only links).
-                var label = map.TryGetValue("label", out var lv) && !string.IsNullOrWhiteSpace(lv?.ToString())
+                // Explicit `label` overrides everything; otherwise a snippet's admonition title is used.
+                var explicitLabel = map.TryGetValue("label", out var lv) && !string.IsNullOrWhiteSpace(lv?.ToString())
                     ? lv!.ToString()!.Trim()
-                    : "Links";
+                    : null;
+
+                // `note_snippet` (or legacy `disclosure_snippet`) points at a markdown snippet whose
+                // content becomes the note. When the snippet is a single admonition, its title/kind
+                // drive the standalone fallback box and its body becomes the tooltip/footnote text.
+                var snippetPath = (map.TryGetValue("note_snippet", out var ns) ? ns?.ToString() : null)
+                                ?? (map.TryGetValue("disclosure_snippet", out var ds) ? ds?.ToString() : null);
+
+                var kind = "info";
+                string? snippetTitle = null;
+                if (!string.IsNullOrWhiteSpace(snippetPath))
+                {
+                    var content = ReadSnippet(snippetPath!, id!);
+                    if (content is not null)
+                    {
+                        (kind, snippetTitle, note) = ExtractNote(content);
+                    }
+                }
 
-                _rules.Add(new Rule(id!, domains, patterns, note!.Trim(), label));
+                if (string.IsNullOrWhiteSpace(note))
+                {
+                    _log.LogWarning("link-notes: rule '{Id}' has no note (inline or snippet); skipping", id);
+                    continue;
+                }
+
+                var label = explicitLabel ?? snippetTitle ?? "Links";
+                _rules.Add(new Rule(id!, domains, patterns, note!.Trim('\n'), label, kind));
             }
         }
 
         if (_rules.Count == 0)
             _log.LogWarning("link-notes: no link rules configured; plugin is a no-op");
     }
 
+    // Resolves a snippet path against the configured base directories and returns its text, or null.
+    private string? ReadSnippet(string path, string ruleId)
+    {
+        if (Path.IsPathRooted(path) && File.Exists(path)) return File.ReadAllText(path);
+        foreach (var basePath in _snippetBasePaths)
+        {
+            var candidate = Path.GetFullPath(Path.Combine(basePath, path));
+            if (File.Exists(candidate)) return File.ReadAllText(candidate);
+        }
+        _log?.LogWarning("link-notes: rule '{Id}' snippet '{Path}' not found; falling back to inline note", ruleId, path);
+        return null;
+    }
+
+    // Splits snippet content into (kind, title, body). If the snippet is a single admonition
+    // (`!!! kind "Title"` with a 4-space indented body), the title/kind are returned and the body is
+    // de-indented so it renders as plain paragraphs inside a footnote tooltip (an admonition cannot
+    // render inside a footnote) while still driving the standalone fallback box. Otherwise the whole
+    // trimmed content is treated as the body with kind "info" and no title.
+    private static (string Kind, string? Title, string Body) ExtractNote(string content)
+    {
+        var text = content.Replace("\r\n", "\n").Trim('\n');
+        var lines = text.Split('\n');
+        var first = lines.Length > 0 ? lines[0] : "";
+        var m = AdmonitionHeader().Match(first);
+        if (!m.Success)
+            return ("info", null, text.Trim());
+
+        var kind = m.Groups["kind"].Value.Trim();
+        if (kind.Length == 0) kind = "info";
+        var title = m.Groups["title"].Success ? m.Groups["title"].Value : null;
+
+        // De-indent the admonition body (strip one 4-space / tab indent from each line).
+        var body = new StringBuilder();
+        for (var i = 1; i < lines.Length; i++)
+        {
+            var line = lines[i];
+            if (line.StartsWith("    ", StringComparison.Ordinal)) line = line[4..];
+            else if (line.StartsWith("\t", StringComparison.Ordinal)) line = line[1..];
+            body.Append(line).Append('\n');
+        }
+        return (kind, string.IsNullOrWhiteSpace(title) ? null : title.Trim(), body.ToString().Trim('\n'));
+    }
+
+    [GeneratedRegex("""^(?:!!!|\?\?\?\+?)\s+(?<kind>[^"\n]*?)\s*(?:"(?<title>[^"]*)")?\s*$""")]
+    private static partial Regex AdmonitionHeader();
+
     public Task<string> ProcessAsync(Page page, string markdown, SiteContext site, CancellationToken ct)
     {
         if (_rules.Count == 0 || markdown.Length == 0) return Task.FromResult(markdown);
@@ -138,15 +220,17 @@ public Task<string> ProcessAsync(Page page, string markdown, SiteContext site, C
         sb.Append("\n\n");
 
         // Footnote definitions for referenced rules: Markdig renders these at the bottom of the
-        // page (the footer note) and links every reference to them (the hover tooltip).
+        // page (the footer note) and links every reference to them (the hover tooltip). Continuation
+        // lines are indented 4 spaces so multi-paragraph notes stay within the footnote definition.
         foreach (var rule in _rules.Where(r => referenced.Contains(r.Id)))
-            sb.Append("[^linknote-").Append(rule.Id).Append("]: ").Append(rule.Note).Append('\n');
+            sb.Append("[^linknote-").Append(rule.Id).Append("]: ")
+              .Append(rule.Note.Replace("\n", "\n    ", StringComparison.Ordinal)).Append('\n');
 
         // 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!!! info \"").Append(rule.Label).Append("\"\n    ");
+            sb.Append("\n!!! ").Append(rule.Kind).Append(" \"").Append(rule.Label).Append("\"\n    ");
             sb.Append(rule.Note.Replace("\n", "\n    ", StringComparison.Ordinal));
             sb.Append('\n');
         }
diff --git a/tests/Netdocs.Core.Tests/LinkNotesPluginTests.cs b/tests/Netdocs.Core.Tests/LinkNotesPluginTests.cs
@@ -30,6 +30,14 @@ private static LinkNotesPlugin Configured(params Dictionary<string, object?>[] r
         return plugin;
     }
 
+    private static LinkNotesPlugin ConfiguredWithRoot(string projectRoot, params Dictionary<string, object?>[] rules)
+    {
+        var opts = new Dictionary<string, object?> { ["rules"] = rules.Cast<object?>().ToList() };
+        var plugin = new LinkNotesPlugin();
+        plugin.Configure(new FakeContext(opts) { Config = new SiteConfig { ProjectRoot = projectRoot } });
+        return plugin;
+    }
+
     private static Dictionary<string, object?> Rule(string name, string[] domains, string note, string? query = null)
     {
         var d = new Dictionary<string, object?>
@@ -260,4 +268,97 @@ public void InvalidRegexPattern_IsSkippedNotThrown()
         var plugin = Configured(d);
         Assert.DoesNotContain("linknote", Run(plugin, "[a](https://ebay.us/x)"));
     }
+
+    [Fact]
+    public void NoteSnippet_Admonition_UsesBodyForFootnoteAndTitleForFallback()
+    {
+        var dir = Path.Combine(Path.GetTempPath(), "netdocs-linknotes-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(dir);
+        try
+        {
+            var snippet =
+                "!!! info \"E-Bay Affiliate Links Used\"\n" +
+                "    This post **DOES** include eBay affiliate links.\n\n" +
+                "    You pay the same price.\n";
+            File.WriteAllText(Path.Combine(dir, "ebay-affiliate.md"), snippet);
+
+            var rule = new Dictionary<string, object?>
+            {
+                ["name"] = "ebay",
+                ["domains"] = new List<object?> { "ebay.us" },
+                ["note_snippet"] = "ebay-affiliate.md",
+            };
+            var plugin = ConfiguredWithRoot(dir, rule);
+
+            // Inline link: footnote definition carries the de-indented body (NOT a nested admonition,
+            // which can't render inside a footnote) so the tooltip shows the text.
+            var inline = Run(plugin, "Buy on [eBay](https://ebay.us/abc).");
+            Assert.Contains("[^linknote-ebay]", inline);
+            Assert.Contains("This post **DOES** include eBay affiliate links.", inline);
+            Assert.DoesNotContain("!!! info", inline);
+            // Continuation lines are indented so the second paragraph stays in the footnote.
+            Assert.Contains("\n    You pay the same price.", inline);
+
+            // Table-only link: standalone admonition reuses the snippet's title as the box header.
+            var table = Run(plugin, "| Item | Buy |\n| --- | --- |\n| Widget | [eBay](https://ebay.us/xyz) |");
+            Assert.Contains("!!! info \"E-Bay Affiliate Links Used\"", table);
+            Assert.Contains("This post **DOES** include eBay affiliate links.", table);
+        }
+        finally
+        {
+            Directory.Delete(dir, recursive: true);
+        }
+    }
+
+    [Fact]
+    public void NoteSnippet_MissingFile_FallsBackToInlineNote()
+    {
+        var dir = Path.Combine(Path.GetTempPath(), "netdocs-linknotes-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(dir);
+        try
+        {
+            var rule = new Dictionary<string, object?>
+            {
+                ["name"] = "ebay",
+                ["domains"] = new List<object?> { "ebay.us" },
+                ["note"] = "Inline fallback note.",
+                ["note_snippet"] = "does-not-exist.md",
+            };
+            var plugin = ConfiguredWithRoot(dir, rule);
+            var result = Run(plugin, "Buy on [eBay](https://ebay.us/abc).");
+            Assert.Contains("[^linknote-ebay]: Inline fallback note.", result);
+        }
+        finally
+        {
+            Directory.Delete(dir, recursive: true);
+        }
+    }
+
+    [Fact]
+    public void NoteSnippet_ResolvesFromDocsSnippetsDir()
+    {
+        var dir = Path.Combine(Path.GetTempPath(), "netdocs-linknotes-" + Guid.NewGuid().ToString("N"));
+        var snippetsDir = Path.Combine(dir, "docs", "snippets");
+        Directory.CreateDirectory(snippetsDir);
+        try
+        {
+            File.WriteAllText(Path.Combine(snippetsDir, "amazon-affiliate.md"),
+                "!!! info \"Amazon Affiliate Links Used\"\n    Amazon disclosure body.\n");
+
+            var rule = new Dictionary<string, object?>
+            {
+                ["name"] = "amazon",
+                ["domains"] = new List<object?> { "amzn.to" },
+                // Bare filename resolves via the conventional <docs>/snippets directory.
+                ["note_snippet"] = "amazon-affiliate.md",
+            };
+            var plugin = ConfiguredWithRoot(dir, rule);
+            var result = Run(plugin, "Buy on [Amazon](https://amzn.to/abc).");
+            Assert.Contains("[^linknote-amazon]: Amazon disclosure body.", result);
+        }
+        finally
+        {
+            Directory.Delete(dir, recursive: true);
+        }
+    }
 }
