docs(rss): document feed output paths + auto social icon

Netdocs · Copilot · Netdocs · commit 08c882783a76 · 2026-07-22T02:04:51.000-05:00
- RssPlugin: opt-in social_icon injects an RSS entry into extra.social,
  linking the RSS feed (or Atom via social_feed: atom). Existing social
  entries are preserved.
- rss.md: clarify feeds are written to the site root at stable URLs, with a
  table of default files + how to configure/serve them; document the new
  social_icon/social_feed options.
- Add 3 unit tests covering the social injection (211 tests pass).

Co-authored-by: Copilot &lt;223556219+Copilot@users.noreply.github.com&gt;
diff --git a/docs-site/docs/plugins/rss.md b/docs-site/docs/plugins/rss.md
@@ -21,6 +21,8 @@ feed. Requires the [blog](blog.md) plugin to have collected posts.
 | `feed_description` | string | `site_description` | Override the feed/channel description. |
 | `image` | string | — | Channel image (logo) URL; relative URLs are resolved against `site_url`. |
 | `ttl` | int | — | RSS `<ttl>` in minutes (advisory cache time for readers). |
+| `social_icon` | bool | `false` | Add the feed as an RSS icon in the header/footer social row (see [Output](#output)). |
+| `social_feed` | string | `rss` | Which feed the social icon links when `social_icon: true` — `rss` or `atom`. |
 
 ```json
 { "name": "rss", "options": { "length": 20, "atom": true, "full_content": false } }
@@ -57,8 +59,28 @@ image: hero.png
 
 ## Output
 
-`site/feed_rss_created.xml` (and `site/feed_atom_created.xml` when `atom: true`) — link them
-from your `extra.social` block or `<head>`:
+Feeds are written to the **root of your built site** (next to `index.html`), so they are served at
+a stable, predictable URL:
+
+| Feed | Default file | Served at | Configure with |
+|---|---|---|---|
+| RSS 2.0 | `feed_rss_created.xml` | `<site_url>/feed_rss_created.xml` | `rss_file` |
+| Atom 1.0 *(when `atom: true`)* | `feed_atom_created.xml` | `<site_url>/feed_atom_created.xml` | `atom_file` |
+
+The RSS feed advertises itself with an `atom:link rel="self"` element so readers can discover the
+canonical feed URL.
+
+### Show the feed as a social icon
+
+Set `social_icon: true` and the plugin adds an RSS entry to your `extra.social` row automatically —
+no manual link needed. It links `feed_rss_created.xml` by default, or the Atom feed with
+`social_feed: atom`:
+
+```json
+{ "name": "rss", "options": { "atom": true, "social_icon": true } }
+```
+
+To place or style the link yourself instead, add it to `extra.social` by hand:
 
 ```json
 "extra": {
@@ -68,9 +90,6 @@ from your `extra.social` block or `<head>`:
 }
 ```
 
-The RSS feed also advertises itself with an `atom:link rel="self"` element so readers can
-discover the canonical feed URL.
-
 ## Attribution
 
 Behavior is modeled on [mkdocs-rss-plugin](https://github.com/Guts/mkdocs-rss-plugin) by @Guts (MIT). See [Attributions](../about/attributions.md).
diff --git a/src/Netdocs.Plugins/RssPlugin.cs b/src/Netdocs.Plugins/RssPlugin.cs
@@ -44,6 +44,35 @@ public void Configure(IPluginContext ctx)
         _feedDescription = o.Get("feed_description").AsString();
         _channelImage = o.Get("image").AsString();
         _ttl = o.Get("ttl").AsInt(0);
+
+        // `social_icon: true` surfaces the feed as an RSS icon in the header/footer social row.
+        // `social_feed: atom` links the Atom feed instead of the default RSS feed.
+        if (o.Get("social_icon").AsBool(false))
+        {
+            var useAtom = string.Equals(o.Get("social_feed").AsString(), "atom", StringComparison.OrdinalIgnoreCase);
+            var feedFile = useAtom ? _atomFile : _rssFile;
+            var siteUrl = (ctx.Config.SiteUrl ?? "").TrimEnd('/');
+            var link = siteUrl.Length > 0 ? $"{siteUrl}/{feedFile}" : "/" + feedFile;
+            AddSocialEntry(ctx.Config, "fontawesome/solid/rss", link);
+        }
+    }
+
+    /// <summary>Appends a <c>{ icon, link }</c> entry to <c>extra.social</c> so the theme renders it
+    /// alongside the other social links. Config's <c>extra</c> map is treated as immutable, so a
+    /// shallow copy is written back with the augmented social list.</summary>
+    private static void AddSocialEntry(SiteConfig config, string icon, string link)
+    {
+        var extra = new Dictionary<string, object?>(config.Extra, StringComparer.OrdinalIgnoreCase);
+        var social = extra.TryGetValue("social", out var existing)
+            ? new List<object?>(existing.AsList())
+            : [];
+        social.Add(new Dictionary<string, object?>(StringComparer.OrdinalIgnoreCase)
+        {
+            ["icon"] = icon,
+            ["link"] = link,
+        });
+        extra["social"] = social;
+        config.Extra = extra;
     }
 
     public async Task OnBuildCompleteAsync(SiteContext site, CancellationToken ct)
diff --git a/tests/Netdocs.Core.Tests/RssPluginTests.cs b/tests/Netdocs.Core.Tests/RssPluginTests.cs
@@ -147,9 +147,57 @@ public async Task Length_LimitsItems()
         Assert.Equal(2, System.Text.RegularExpressions.Regex.Matches(xml, "<item>").Count);
     }
 
-    private sealed class FakeContext(IReadOnlyDictionary<string, object?> options) : IPluginContext
+    [Fact]
+    public void SocialIcon_AddsRssFeedEntryToExtraSocial()
+    {
+        var config = new SiteConfig { SiteUrl = "https://example.com/" };
+        var plugin = new RssPlugin();
+        plugin.Configure(new FakeContext(new Dictionary<string, object?> { ["social_icon"] = true }, config));
+
+        Assert.True(config.Extra.TryGetValue("social", out var socialObj));
+        var social = Assert.IsAssignableFrom<System.Collections.IEnumerable>(socialObj).Cast<object?>().ToList();
+        var entry = Assert.IsAssignableFrom<IDictionary<string, object?>>(social.Single());
+        Assert.Equal("fontawesome/solid/rss", entry["icon"]);
+        Assert.Equal("https://example.com/feed_rss_created.xml", entry["link"]);
+    }
+
+    [Fact]
+    public void SocialFeedAtom_LinksAtomFeed()
+    {
+        var config = new SiteConfig { SiteUrl = "https://example.com" };
+        var plugin = new RssPlugin();
+        plugin.Configure(new FakeContext(
+            new Dictionary<string, object?> { ["social_icon"] = true, ["social_feed"] = "atom" }, config));
+
+        var social = ((System.Collections.IEnumerable)config.Extra["social"]!).Cast<object?>().ToList();
+        var entry = (IDictionary<string, object?>)social.Single()!;
+        Assert.Equal("https://example.com/feed_atom_created.xml", entry["link"]);
+    }
+
+    [Fact]
+    public void SocialIcon_PreservesExistingSocialEntries()
+    {
+        var config = new SiteConfig
+        {
+            SiteUrl = "https://example.com",
+            Extra = new Dictionary<string, object?>
+            {
+                ["social"] = new List<object?>
+                {
+                    new Dictionary<string, object?> { ["icon"] = "fontawesome/brands/github", ["link"] = "https://github.com/x" },
+                },
+            },
+        };
+        var plugin = new RssPlugin();
+        plugin.Configure(new FakeContext(new Dictionary<string, object?> { ["social_icon"] = true }, config));
+
+        var social = ((System.Collections.IEnumerable)config.Extra["social"]!).Cast<object?>().ToList();
+        Assert.Equal(2, social.Count);
+    }
+
+    private sealed class FakeContext(IReadOnlyDictionary<string, object?> options, SiteConfig? config = null) : IPluginContext
     {
-        public SiteConfig Config { get; } = new();
+        public SiteConfig Config { get; } = config ?? new();
         public BuildOptions Options { get; } = new();
         public Microsoft.Extensions.Logging.ILogger Logger { get; } = NullLogger.Instance;
         public Microsoft.Extensions.DependencyInjection.IServiceCollection Services { get; }
