feat(redirects): support per-page redirect_from front matter

Pages can now declare the old URLs they replace directly in front matter
under `redirect_from` (or `aliases`), as a string or list. Each emits a
client-side redirect to that page's current URL, so a page's historical
locations live next to the content and move with it when it is renamed.

Front-matter redirects merge with `redirect_maps`/`redirect_files`; an
explicitly configured entry still wins on a conflicting source.

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

Author: Netdocs

src/Netdocs.Plugins/RedirectsPlugin.cs

@@ -9,17 +9,21 @@ namespace Netdocs.Plugins;
 /// Emits client-side redirect pages (an <c>index.html</c> with a canonical link plus a
 /// <c>meta refresh</c>) for every <c>source → target</c> mapping.
 ///
-/// Mappings come from two places, merged together:
+/// Mappings come from three places, merged together:
 /// <list type="bullet">
+///   <item>Per-page front matter — a page may list the old URLs it replaces under
+///     <c>redirect_from</c> (or <c>aliases</c>), as a single string or a list. Each becomes a
+///     redirect to that page's current URL. This keeps a page's old locations next to the page
+///     itself, so a redirect travels with the content when it is renamed or moved.</item>
 ///   <item><c>redirect_maps</c> — an inline object of <c>{ "old/path": "new/url" }</c> pairs.</item>
 ///   <item><c>redirect_files</c> — a single path or an array of paths to JSON file(s) holding
 ///     bulk redirects. Each file may be either an object map <c>{ "old/path": "new/url" }</c>
 ///     or an array of objects <c>[{ "source": "old/path", "target": "new/url", "status": 308 }]</c>.
 ///     Paths are resolved relative to the project root, then the docs directory, then treated as
 ///     absolute. This lets large migration redirect tables live outside the config file.</item>
 /// </list>
-/// Later entries win on conflict, so an inline <c>redirect_maps</c> value overrides one loaded
-/// from a file with the same source.
+/// Later entries win on conflict, so an explicitly configured <c>redirect_maps</c>/<c>redirect_files</c>
+/// value overrides a per-page <c>redirect_from</c> for the same source.
 /// </summary>
 public sealed class RedirectsPlugin : IPlugin, IBuildHook
 {
@@ -58,7 +62,13 @@ public void Configure(IPluginContext ctx)
 
     public async Task OnBuildCompleteAsync(SiteContext site, CancellationToken ct)
     {
+        // Merge sources: per-page front matter first, then explicitly configured maps (which win).
+        var redirects = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
+        CollectFrontMatterRedirects(site, redirects);
         foreach (var (source, target) in _maps)
+            redirects[source] = target;
+
+        foreach (var (source, target) in redirects)
         {
             var relative = OutputPathFor(source);
             var dest = Path.Combine(site.Config.AbsoluteSiteDir, relative.Replace('/', Path.DirectorySeparatorChar));
@@ -80,6 +90,40 @@ public async Task OnBuildCompleteAsync(SiteContext site, CancellationToken ct)
         }
     }
 
+    /// <summary>Collects redirects declared in page front matter (<c>redirect_from</c> or
+    /// <c>aliases</c>), each pointing at that page's current site-relative URL.</summary>
+    private static void CollectFrontMatterRedirects(SiteContext site, Dictionary<string, string> into)
+    {
+        foreach (var page in site.Pages)
+        {
+            if (string.IsNullOrWhiteSpace(page.Url)) continue;
+            var target = "/" + page.Url.TrimStart('/');
+
+            foreach (var key in new[] { "redirect_from", "aliases" })
+            {
+                if (!page.FrontMatter.TryGetValue(key, out var value)) continue;
+                foreach (var source in AsStrings(value))
+                    into[source] = target;
+            }
+        }
+    }
+
+    /// <summary>Yields the trimmed string values of a front-matter scalar or list.</summary>
+    private static IEnumerable<string> AsStrings(object? value)
+    {
+        switch (value)
+        {
+            case string s when s.Trim().Length > 0:
+                yield return s.Trim();
+                break;
+            case IEnumerable<object?> list:
+                foreach (var item in list)
+                    if (item?.ToString() is { } s && s.Trim().Length > 0)
+                        yield return s.Trim();
+                break;
+        }
+    }
+
     /// <summary>Maps a redirect source path to the relative output HTML file it is written to.</summary>
     private static string OutputPathFor(string source)
     {

tests/Netdocs.Core.Tests/RedirectsPluginTests.cs

@@ -30,6 +30,14 @@ private SiteContext Site()
         return site;
     }
 
+    private static Page PageWith(string url, string frontMatterKey, object? value) => new()
+    {
+        SourcePath = "x",
+        RelativePath = url + ".md",
+        Url = url + "/",
+        FrontMatter = new Dictionary<string, object?> { [frontMatterKey] = value },
+    };
+
     private async Task<SiteContext> Run(IReadOnlyDictionary<string, object?> options)
     {
         var site = Site();
@@ -137,6 +145,63 @@ public async Task MissingFile_DoesNotThrow()
             Directory.EnumerateFiles(site.Config.AbsoluteSiteDir).Any());
     }
 
+    [Fact]
+    public async Task FrontMatter_RedirectFromString_EmitsStubToPageUrl()
+    {
+        var site = Site();
+        site.Pages.Add(PageWith("blog/2018/ls-how-to-turn-on-the-alternator",
+            "redirect_from", "blog/2018/ls--how-to-turn-on-the-alternator/"));
+        var plugin = new RedirectsPlugin();
+        plugin.Configure(new FakeContext(new Dictionary<string, object?>(), site.Config));
+        await plugin.OnBuildCompleteAsync(site, default);
+
+        var html = ReadStub(site, "blog/2018/ls--how-to-turn-on-the-alternator/index.html");
+        Assert.Contains("url=/blog/2018/ls-how-to-turn-on-the-alternator/", html);
+    }
+
+    [Fact]
+    public async Task FrontMatter_RedirectFromList_EmitsStubPerEntry()
+    {
+        var site = Site();
+        site.Pages.Add(PageWith("new/page", "redirect_from",
+            new List<object?> { "old/a/", "old/b/" }));
+        var plugin = new RedirectsPlugin();
+        plugin.Configure(new FakeContext(new Dictionary<string, object?>(), site.Config));
+        await plugin.OnBuildCompleteAsync(site, default);
+
+        Assert.Contains("url=/new/page/", ReadStub(site, "old/a/index.html"));
+        Assert.Contains("url=/new/page/", ReadStub(site, "old/b/index.html"));
+    }
+
+    [Fact]
+    public async Task FrontMatter_AliasesKey_AlsoSupported()
+    {
+        var site = Site();
+        site.Pages.Add(PageWith("new/page", "aliases", "legacy/x/"));
+        var plugin = new RedirectsPlugin();
+        plugin.Configure(new FakeContext(new Dictionary<string, object?>(), site.Config));
+        await plugin.OnBuildCompleteAsync(site, default);
+
+        Assert.Contains("url=/new/page/", ReadStub(site, "legacy/x/index.html"));
+    }
+
+    [Fact]
+    public async Task ConfiguredMap_OverridesFrontMatterForSameSource()
+    {
+        var site = Site();
+        site.Pages.Add(PageWith("from-frontmatter", "redirect_from", "dup/"));
+        var plugin = new RedirectsPlugin();
+        plugin.Configure(new FakeContext(
+            new Dictionary<string, object?>
+            {
+                ["redirect_maps"] = new Dictionary<string, object?> { ["dup/"] = "/from-config/" },
+            },
+            site.Config));
+        await plugin.OnBuildCompleteAsync(site, default);
+
+        Assert.Contains("url=/from-config/", ReadStub(site, "dup/index.html"));
+    }
+
     private sealed class FakeContext(IReadOnlyDictionary<string, object?> options, SiteConfig config) : IPluginContext
     {
         public SiteConfig Config { get; } = config;