feat(rss): render HTML descriptions and support stable rss_guid

Feed item descriptions previously carried the raw markdown excerpt, so readers
showed unrendered syntax (e.g. leaked "[text](file.md){target=_blank}") instead
of formatted text. Build the description from the post's rendered HTML intro
instead: the content before the <!-- more --> marker (mirroring the on-site
excerpt), or the first paragraph when there's no marker. The leading tag nav and
H1 are stripped (the item already has a title), and relative links/images are
absolutized so they resolve in any reader.

Also add an `rss_guid` front-matter override. The guid identifies each item, and
defaults to the post permalink, so changing a slug/URL changes the guid and makes
readers re-surface the post as new. Pinning `rss_guid` keeps a post's identity
stable across such a move (emitted with isPermaLink="false", and used as the Atom
entry id too). This lets a site backfill stable guids before a URL cutover.

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

Author: 2 people

docs-site/docs/plugins/rss.md

@@ -39,12 +39,26 @@ the derived defaults:
 | `link` / `id` | `site_url` + post URL | — |
 | `pubDate` / `published`, `updated` | Post creation date | — |
 | `category` (RSS) / `category term` (Atom) | Blog `categories` | — |
-| `description` / `summary` | Post excerpt | `rss_description` |
+| `description` / `summary` | Rendered HTML of the post intro (content before `<!-- more -->`, or the first paragraph) | `rss_description` |
 | `content:encoded` / `content` | Rendered HTML *(only when `full_content: true`)* | — |
 | `enclosure` (RSS image) | Front-matter `image`, else the first `<img>` in the post | `image` |
+| `guid` (RSS) / `id` (Atom) | `site_url` + post URL (`isPermaLink="true"`) | `rss_guid` |
 
 Relative image paths are resolved against the post URL; a leading `/` is resolved against
-`site_url`; absolute (`http(s)://`) URLs are used as-is.
+`site_url`; absolute (`http(s)://`) URLs are used as-is. Links and images inside the rendered
+`description` are absolutized the same way so they resolve in any reader.
+
+### Stable GUIDs across URL changes
+
+The `guid` (RSS) / `id` (Atom) uniquely identifies each item; readers use it to tell new posts
+from ones they've already shown. By default it's the post's permalink, so **changing a post's
+slug or URL changes its guid**, and readers re-surface it as new. To keep a post's identity
+stable across such a move, pin an explicit `rss_guid` in front matter (any stable string — a URN,
+a UUID, or the post's original URL). When set, the guid is emitted with `isPermaLink="false"`:
+
+```yaml
+rss_guid: https://static.xtremeownage.com/blog/2024/01/04/power-consumption-versus-price/
+```
 
 Example front matter using the overrides:
 
@@ -53,6 +67,7 @@ Example front matter using the overrides:
 title: My Post
 rss_title: A snappier title just for feed readers
 rss_description: A custom one-line summary for the feed.
+rss_guid: urn:uuid:1e5f2c9a-0b3d-4a1e-9c2f-8b7a6d5e4c3b
 image: hero.png
 ---
 ```

src/Netdocs.Plugins/RssPlugin.cs

@@ -98,10 +98,15 @@ private FeedItem ToItem(BlogPost post, string siteUrl)
         var page = post.Page;
         var url = $"{siteUrl}/{page.Url}";
         var title = FrontMatterString(page, "rss_title") ?? page.Title;
-        var description = FrontMatterString(page, "rss_description") ?? post.Excerpt;
+        var description = FrontMatterString(page, "rss_description")
+            ?? BuildDescriptionHtml(page, url)
+            ?? post.Excerpt;
+        // A stable guid overrides the (URL-derived) permalink guid so a later slug/URL change
+        // doesn't make readers re-surface every post as new. Backfill `rss_guid` in front matter.
+        var guid = FrontMatterString(page, "rss_guid");
         var image = ResolveImage(page, url, siteUrl);
         var content = _fullContent && page.HtmlContent.Length > 0 ? page.HtmlContent : null;
-        return new FeedItem(title, url, post.Date, post.Categories, description, image, content);
+        return new FeedItem(title, url, guid, post.Date, post.Categories, description, image, content);
     }
 
     private string BuildRss(SiteContext site, string siteUrl, List<FeedItem> items)
@@ -152,8 +157,16 @@ private string BuildRss(SiteContext site, string siteUrl, List<FeedItem> items)
             writer.WriteElementString("title", item.Title);
             writer.WriteElementString("link", item.Url);
             writer.WriteStartElement("guid");
-            writer.WriteAttributeString("isPermaLink", "true");
-            writer.WriteString(item.Url);
+            if (item.Guid is { Length: > 0 } guid)
+            {
+                writer.WriteAttributeString("isPermaLink", "false");
+                writer.WriteString(guid);
+            }
+            else
+            {
+                writer.WriteAttributeString("isPermaLink", "true");
+                writer.WriteString(item.Url);
+            }
             writer.WriteEndElement();
             writer.WriteElementString("pubDate", item.Date.ToString("r"));
             foreach (var category in item.Categories)
@@ -204,7 +217,7 @@ private string BuildAtom(SiteContext site, string siteUrl, List<FeedItem> items)
         {
             writer.WriteStartElement("entry");
             writer.WriteElementString("title", item.Title);
-            writer.WriteElementString("id", item.Url);
+            writer.WriteElementString("id", item.Guid is { Length: > 0 } aid ? aid : item.Url);
             writer.WriteElementString("updated", item.Date.ToString("yyyy-MM-ddTHH:mm:sszzz"));
             writer.WriteElementString("published", item.Date.ToString("yyyy-MM-ddTHH:mm:sszzz"));
             writer.WriteStartElement("link");
@@ -292,9 +305,76 @@ private static string MimeForImage(string url) =>
     [GeneratedRegex("""<img[^>]+src=["']([^"']+)["']""", RegexOptions.IgnoreCase)]
     private static partial Regex FirstImage();
 
+    /// <summary>
+    /// Builds a rendered-HTML description from the post's content so feed readers show formatted
+    /// text instead of raw markdown. Uses the intro region — everything before the
+    /// <c>&lt;!-- more --&gt;</c> marker, mirroring the on-site excerpt — or the first paragraph
+    /// when the post has no marker. Leading tag navigation and the H1 (the item already carries a
+    /// title) are stripped, and relative links/images are absolutized so they resolve in a reader.
+    /// </summary>
+    private static string? BuildDescriptionHtml(Page page, string postUrl)
+    {
+        var html = page.HtmlContent;
+        if (string.IsNullOrWhiteSpace(html)) return null;
+
+        var moreIdx = html.IndexOf("<!-- more -->", StringComparison.OrdinalIgnoreCase);
+        string region;
+        if (moreIdx >= 0)
+        {
+            region = html[..moreIdx];
+        }
+        else
+        {
+            var first = FirstParagraph().Match(html);
+            if (!first.Success) return null;
+            region = first.Value;
+        }
+
+        region = LeadingTagsNav().Replace(region, "");
+        region = LeadingHeading().Replace(region, "");
+        region = AbsolutizeUrls(region.Trim(), postUrl);
+        return region.Length > 0 ? region : null;
+    }
+
+    /// <summary>Rewrites relative <c>href</c>/<c>src</c> values to absolute URLs, resolved against
+    /// the post's canonical URL, so links and images in a feed description work in any reader.</summary>
+    private static string AbsolutizeUrls(string html, string postUrl)
+    {
+        if (!Uri.TryCreate(postUrl.EndsWith('/') ? postUrl : postUrl + "/", UriKind.Absolute, out var baseUri))
+            return html;
+
+        return HrefOrSrc().Replace(html, match =>
+        {
+            var attr = match.Groups[1].Value;
+            var value = match.Groups[2].Value;
+            if (value.Length == 0 || value.StartsWith('#') || value.Contains("://") ||
+                value.StartsWith("mailto:", StringComparison.OrdinalIgnoreCase) ||
+                value.StartsWith("tel:", StringComparison.OrdinalIgnoreCase) ||
+                value.StartsWith("data:", StringComparison.OrdinalIgnoreCase))
+                return match.Value;
+
+            return Uri.TryCreate(baseUri, value, out var abs)
+                ? $"{attr}=\"{abs}\""
+                : match.Value;
+        });
+    }
+
+    [GeneratedRegex("""<p\b[^>]*>.*?</p>""", RegexOptions.IgnoreCase | RegexOptions.Singleline)]
+    private static partial Regex FirstParagraph();
+
+    [GeneratedRegex("""^\s*<nav\b[^>]*class="[^"]*md-tags[^"]*"[^>]*>.*?</nav>""", RegexOptions.IgnoreCase | RegexOptions.Singleline)]
+    private static partial Regex LeadingTagsNav();
+
+    [GeneratedRegex("""^\s*<h1\b[^>]*>.*?</h1>""", RegexOptions.IgnoreCase | RegexOptions.Singleline)]
+    private static partial Regex LeadingHeading();
+
+    [GeneratedRegex("\\b(href|src)\\s*=\\s*\"([^\"]*)\"", RegexOptions.IgnoreCase)]
+    private static partial Regex HrefOrSrc();
+
     private sealed record FeedItem(
         string Title,
         string Url,
+        string? Guid,
         DateTimeOffset Date,
         IReadOnlyList<string> Categories,
         string Description,

tests/Netdocs.Core.Tests/RssPluginTests.cs

@@ -103,6 +103,69 @@ public async Task RssChannel_IncludesStandardMetadata()
         Assert.Contains("<pubDate>", xml);
     }
 
+    [Fact]
+    public async Task Guid_DefaultsToPermalinkUrl()
+    {
+        var site = Site(Post("Hello", "blog/hello", DateTimeOffset.UtcNow));
+        await Run(new Dictionary<string, object?>(), site);
+
+        var xml = File.ReadAllText(Path.Combine(_root, "feed_rss_created.xml"));
+        Assert.Contains("<guid isPermaLink=\"true\">https://example.com/blog/hello/</guid>", xml);
+    }
+
+    [Fact]
+    public async Task RssGuidFrontMatter_OverridesPermalinkGuid()
+    {
+        var fm = new Dictionary<string, object?> { ["rss_guid"] = "urn:uuid:stable-123" };
+        var site = Site(Post("Renamed", "blog/new-slug", DateTimeOffset.UtcNow, frontMatter: fm));
+        await Run(new Dictionary<string, object?>(), site);
+
+        var xml = File.ReadAllText(Path.Combine(_root, "feed_rss_created.xml"));
+        Assert.Contains("<guid isPermaLink=\"false\">urn:uuid:stable-123</guid>", xml);
+        // The stable id also anchors the Atom entry.
+        await Run(new Dictionary<string, object?> { ["atom"] = true }, site);
+        var atom = File.ReadAllText(Path.Combine(_root, "feed_atom_created.xml"));
+        Assert.Contains("<id>urn:uuid:stable-123</id>", atom);
+    }
+
+    [Fact]
+    public async Task Description_UsesRenderedHtmlBeforeMoreMarker()
+    {
+        var html = "<h1 id=\"t\">Title</h1>\n<p>Intro <strong>bold</strong>.</p>\n<!-- more -->\n<p>Rest</p>";
+        var site = Site(Post("Post", "blog/p", DateTimeOffset.UtcNow, html: html));
+        await Run(new Dictionary<string, object?>(), site);
+
+        var xml = File.ReadAllText(Path.Combine(_root, "feed_rss_created.xml"));
+        // HTML is escaped inside <description>; the intro paragraph (with formatting) is present,
+        // the leading H1 is stripped, and content after <!-- more --> is excluded.
+        Assert.Contains("&lt;p&gt;Intro &lt;strong&gt;bold&lt;/strong&gt;.&lt;/p&gt;", xml);
+        Assert.DoesNotContain("Title", xml.Split("<description>")[1].Split("</description>")[0]);
+        Assert.DoesNotContain("Rest", xml);
+    }
+
+    [Fact]
+    public async Task Description_AbsolutizesRelativeLinks()
+    {
+        var html = "<p>See <a href=\"../other/\">this</a>.</p>\n<!-- more -->\n<p>x</p>";
+        var site = Site(Post("Post", "blog/2024/p", DateTimeOffset.UtcNow, html: html));
+        await Run(new Dictionary<string, object?>(), site);
+
+        var xml = File.ReadAllText(Path.Combine(_root, "feed_rss_created.xml"));
+        Assert.Contains("https://example.com/blog/2024/other/", xml);
+    }
+
+    [Fact]
+    public async Task RssDescriptionFrontMatter_WinsOverRenderedHtml()
+    {
+        var fm = new Dictionary<string, object?> { ["rss_description"] = "Custom summary" };
+        var html = "<p>Intro</p>\n<!-- more -->\n<p>Rest</p>";
+        var site = Site(Post("Post", "blog/p", DateTimeOffset.UtcNow, html: html, frontMatter: fm));
+        await Run(new Dictionary<string, object?>(), site);
+
+        var xml = File.ReadAllText(Path.Combine(_root, "feed_rss_created.xml"));
+        Assert.Contains("<description>Custom summary</description>", xml);
+    }
+
     [Fact]
     public async Task PerPostTitleOverride_WinsOverPageTitle()
     {