feat(redirects): generate redirects automatically on a slugify change

Netdocs · Copilot · Netdocs · commit 6d32137f0e03 · 2026-07-27T10:19:47.000-05:00
Add a `slugify_redirects` option to the redirects plugin holding one or
more previous slugify configurations. At build completion every page URL
that the current slugify config would produce is re-slugified under each
old config; where the old slug differs, a redirect from the old URL to
the current URL is generated. This means changing a slugify parameter
(e.g. the separator) no longer silently breaks existing links.

- Generic across all URL-producing plugins (blog, tags, content) with no
  duplication of per-plugin slug logic; keyed only off the final URL.
- Only URLs the current config would itself produce are considered, so
  hand-authored non-slugified paths are left untouched.
- Never emits a stub at a path occupied by a real page.
- Precedence: generated slugify redirects (lowest), then per-page
  redirect_from, then configured redirect_maps/redirect_files (highest).

Adds 5 tests and documents the option with its separator/case coverage
and the ascii-folding limitation.

Co-authored-by: Copilot &lt;223556219+Copilot@users.noreply.github.com&gt;
diff --git a/docs-site/docs/plugins/redirects.md b/docs-site/docs/plugins/redirects.md
@@ -7,15 +7,18 @@ title: redirects
 Emits tiny client-side redirect pages that forward old URLs to new destinations. Useful
 for vanity links and for preserving inbound links after restructuring.
 
-Redirects can be declared in three ways, from most to least local:
+Redirects can be declared in four ways, from most to least local:
 
 1. **Per-page front matter** (`redirect_from`) — recommended for content that moved or was
    renamed, because the old URLs live next to the page and travel with it.
 2. **`redirect_maps`** — a small inline table in the config.
 3. **`redirect_files`** — one or more external JSON files for large bulk tables.
+4. **`slugify_redirects`** — generated automatically when the site's `slugify` settings change,
+   so old slugified URLs keep resolving.
 
-All three are merged. On a conflicting source, an explicitly configured `redirect_maps`/
-`redirect_files` entry wins over a per-page `redirect_from`.
+All are merged. Precedence, from lowest to highest: generated `slugify_redirects`, then per-page
+`redirect_from`, then explicitly configured `redirect_maps`/`redirect_files`. So an explicit
+redirect always overrides an automatically generated one for the same source.
 
 ## Per-page redirects (`redirect_from`)
 
@@ -40,6 +43,7 @@ No plugin options are required for this; just enable the `redirects` plugin.
 |---|---|---|---|
 | `redirect_maps` | object | — | Inline map of source path → destination URL. |
 | `redirect_files` | string \| array | — | One or more JSON files holding bulk redirects. |
+| `slugify_redirects` | object \| array | — | One or more *previous* slugify configs; old URLs are regenerated and redirected to current ones. |
 
 ```json
 {
@@ -99,6 +103,57 @@ with the same source. Sources with a leading slash are normalized relative to th
 directory. A missing or malformed file logs a warning and is skipped rather than failing the
 build.
 
+## Automatic redirects on a slugify change (`slugify_redirects`)
+
+URLs for blog posts, categories, authors, tags and (when `slugify.urls` is on) content pages are
+derived from the site's `slugify` settings — the casing, word separator and ASCII folding. If you
+later change any of those settings, every affected URL changes too, silently breaking existing
+inbound links and bookmarks.
+
+`slugify_redirects` fixes that. List the **previous** slugify configuration(s) and, on the next
+build, every current URL is re-slugified under each old configuration; wherever the old slug
+differs from the current one, a redirect from the old URL to the current URL is generated
+automatically. You do not have to enumerate individual pages.
+
+```json
+{
+  "name": "redirects",
+  "options": {
+    "slugify_redirects": { "case": "lower", "separator": "_" }
+  }
+}
+```
+
+The example above says "we used to slugify with an underscore separator." After switching the
+site's `slugify.separator` to `-`, a post now at `/blog/2018/ls-how-to/` also answers at its old
+`/blog/2018/ls_how_to/` URL.
+
+Provide an array to record several historical changes at once:
+
+```json
+{
+  "name": "redirects",
+  "options": {
+    "slugify_redirects": [
+      { "separator": "_" },
+      { "case": "upper", "separator": "-" }
+    ]
+  }
+}
+```
+
+Each entry accepts the same keys as the site-level `slugify` block: `case` (`lower` \| `upper` \|
+`none`, default `lower`), `separator` (default `-`), and `ascii` (default `false`).
+
+**Notes and limits**
+
+- Only URLs that the **current** slugify config would itself produce are considered, so
+  hand-authored, non-slugified paths are left untouched.
+- A generated redirect is never written at a path already occupied by a real page.
+- Old URLs are reconstructed by re-slugifying the current URL, which captures `separator` and
+  `case` changes. A change to `ascii` folding cannot be reconstructed — the dropped characters are
+  already gone from the current URL — so handle those with an explicit `redirect_from` on the page.
+
 ## Attribution
 
 Behavior is modeled on [mkdocs-redirects](https://github.com/mkdocs/mkdocs-redirects) (MIT). See [Attributions](../about/attributions.md).
diff --git a/src/Netdocs.Plugins/RedirectsPlugin.cs b/src/Netdocs.Plugins/RedirectsPlugin.cs
@@ -21,18 +21,36 @@ namespace Netdocs.Plugins;
 ///     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>
+///   <item><c>slugify_redirects</c> — one or more <em>previous</em> slugify configurations
+///     (each an object of <c>{ "case", "separator", "ascii" }</c>, or an array of them). When the
+///     site's <c>slugify</c> settings change, every page's URL is re-slugified under each old
+///     configuration; wherever the old slug differs from the current one, a redirect from the old
+///     URL to the current URL is generated automatically. This means changing a slugify parameter
+///     (for example the separator from <c>_</c> to <c>-</c>) does not silently break every existing
+///     link — the old URLs keep resolving. Only URLs that the <em>current</em> slugify config would
+///     itself produce are considered (so hand-authored, non-slugified paths are left untouched), and
+///     a generated redirect is never emitted at a path already occupied by a real page.
+///     Note: this reconstructs old URLs by re-slugifying the current URL, so it captures
+///     <c>separator</c> and <c>case</c> changes; a change to <c>ascii</c> folding cannot be
+///     reconstructed (the dropped characters are already gone) and should be handled with an explicit
+///     <c>redirect_from</c>.</item>
 /// </list>
-/// 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.
+/// Merge order (later wins): generated <c>slugify_redirects</c>, then per-page <c>redirect_from</c>,
+/// then explicitly configured <c>redirect_maps</c>/<c>redirect_files</c>. So an explicit redirect
+/// always overrides an automatically generated one for the same source.
 /// </summary>
 public sealed class RedirectsPlugin : IPlugin, IBuildHook
 {
     private readonly Dictionary<string, string> _maps = new(StringComparer.OrdinalIgnoreCase);
+    private readonly List<SlugifyConfig> _slugifyOldConfigs = [];
 
     public string Name => "redirects";
 
     public void Configure(IPluginContext ctx)
     {
+        // Previous slugify configuration(s), used to regenerate old URLs after a slugify change.
+        _slugifyOldConfigs.AddRange(ParseSlugifyConfigs(ctx.PluginOptions));
+
         // 1) External JSON file(s) first, so inline entries can override them.
         foreach (var file in FileList(ctx.PluginOptions))
         {
@@ -62,8 +80,10 @@ 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).
+        // Merge sources (lowest precedence first): generated slugify redirects, then per-page
+        // front matter, then explicitly configured maps (which win).
         var redirects = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
+        CollectSlugifyRedirects(site, redirects);
         CollectFrontMatterRedirects(site, redirects);
         foreach (var (source, target) in _maps)
             redirects[source] = target;
@@ -124,6 +144,93 @@ private static IEnumerable<string> AsStrings(object? value)
         }
     }
 
+    /// <summary>Generates redirects for a slugify-configuration change: every page URL that the
+    /// current slugify config would produce is re-slugified under each previously configured
+    /// slugify config; where the old slug differs, a redirect from the old URL to the current URL
+    /// is added. Sources that collide with a real page URL are skipped so a stub never clobbers an
+    /// actual page.</summary>
+    private void CollectSlugifyRedirects(SiteContext site, Dictionary<string, string> into)
+    {
+        if (_slugifyOldConfigs.Count == 0) return;
+
+        var current = site.Config.Slugify;
+        var pageUrls = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+        foreach (var page in site.Pages)
+            if (!string.IsNullOrWhiteSpace(page.Url))
+                pageUrls.Add(page.Url.Trim().Trim('/'));
+
+        foreach (var page in site.Pages)
+        {
+            if (string.IsNullOrWhiteSpace(page.Url)) continue;
+            var cur = page.Url.Trim().TrimStart('/');
+
+            // Only act on URLs the current slugify config would itself produce; this leaves
+            // hand-authored, non-slugified paths (e.g. when slugify.urls is off) untouched.
+            if (!string.Equals(ReSlugifyUrl(cur, current), EnsureTrailingSlash(cur), StringComparison.Ordinal))
+                continue;
+
+            var target = "/" + cur.TrimStart('/');
+            foreach (var old in _slugifyOldConfigs)
+            {
+                var oldUrl = ReSlugifyUrl(cur, old);
+                if (string.Equals(oldUrl, EnsureTrailingSlash(cur), StringComparison.Ordinal)) continue; // unchanged
+                if (pageUrls.Contains(oldUrl.Trim('/'))) continue;                                        // would clobber a real page
+                into[oldUrl] = target;
+            }
+        }
+    }
+
+    /// <summary>Re-slugifies each path segment of a site-relative URL under the given config,
+    /// preserving <c>.</c> (matching content-URL slugification), and returns it with a trailing
+    /// slash. An empty URL (site root) maps to the empty string.</summary>
+    private static string ReSlugifyUrl(string url, SlugifyConfig config)
+    {
+        var trimmed = url.Trim().Trim('/');
+        if (trimmed.Length == 0) return "";
+        var segments = trimmed.Split('/');
+        return string.Join('/', segments.Select(s => Slug.Make(s, config, "."))) + "/";
+    }
+
+    private static string EnsureTrailingSlash(string url)
+    {
+        var trimmed = url.Trim().Trim('/');
+        return trimmed.Length == 0 ? "" : trimmed + "/";
+    }
+
+    /// <summary>Parses the <c>slugify_redirects</c> option, which may be a single object
+    /// (<c>{ case, separator, ascii }</c>) or an array of such objects.</summary>
+    private static IEnumerable<SlugifyConfig> ParseSlugifyConfigs(IReadOnlyDictionary<string, object?> options)
+    {
+        if (!options.TryGetValue("slugify_redirects", out var value) || value is null)
+            yield break;
+
+        switch (value)
+        {
+            case IReadOnlyDictionary<string, object?> single:
+                yield return ToSlugifyConfig(single);
+                break;
+            case IEnumerable<object?> list:
+                foreach (var item in list)
+                    if (item is IReadOnlyDictionary<string, object?> m)
+                        yield return ToSlugifyConfig(m);
+                break;
+        }
+    }
+
+    private static SlugifyConfig ToSlugifyConfig(IReadOnlyDictionary<string, object?> m) => new()
+    {
+        Case = m.TryGetValue("case", out var c) && c?.ToString() is { Length: > 0 } cs ? cs : "lower",
+        Separator = m.TryGetValue("separator", out var s) && s?.ToString() is { } ss ? ss : "-",
+        Ascii = m.TryGetValue("ascii", out var a) && ToBool(a),
+    };
+
+    private static bool ToBool(object? value) => value switch
+    {
+        bool b => b,
+        string s => string.Equals(s.Trim(), "true", StringComparison.OrdinalIgnoreCase),
+        _ => false,
+    };
+
     /// <summary>Maps a redirect source path to the relative output HTML file it is written to.</summary>
     private static string OutputPathFor(string source)
     {
diff --git a/tests/Netdocs.Core.Tests/RedirectsPluginTests.cs b/tests/Netdocs.Core.Tests/RedirectsPluginTests.cs
@@ -202,6 +202,105 @@ public async Task ConfiguredMap_OverridesFrontMatterForSameSource()
         Assert.Contains("url=/from-config/", ReadStub(site, "dup/index.html"));
     }
 
+    [Fact]
+    public async Task SlugifyRedirect_SeparatorChange_EmitsRedirectToCurrentUrl()
+    {
+        var site = Site();
+        site.Pages.Add(new Page { SourcePath = "x", RelativePath = "x.md", Url = "blog/2018/ls-how-to-turn-on/" });
+        var plugin = new RedirectsPlugin();
+        plugin.Configure(new FakeContext(
+            new Dictionary<string, object?>
+            {
+                ["slugify_redirects"] = new Dictionary<string, object?> { ["separator"] = "_" },
+            },
+            site.Config));
+        await plugin.OnBuildCompleteAsync(site, default);
+
+        var html = ReadStub(site, "blog/2018/ls_how_to_turn_on/index.html");
+        Assert.Contains("url=/blog/2018/ls-how-to-turn-on/", html);
+    }
+
+    [Fact]
+    public async Task SlugifyRedirect_NoConfigChange_EmitsNothing()
+    {
+        var site = Site();
+        site.Pages.Add(new Page { SourcePath = "x", RelativePath = "x.md", Url = "blog/ls-how-to/" });
+        var plugin = new RedirectsPlugin();
+        plugin.Configure(new FakeContext(
+            new Dictionary<string, object?>
+            {
+                // Same as the current default slugify (lower / "-"), so no URL changes.
+                ["slugify_redirects"] = new Dictionary<string, object?> { ["separator"] = "-", ["case"] = "lower" },
+            },
+            site.Config));
+        await plugin.OnBuildCompleteAsync(site, default);
+
+        Assert.False(Directory.Exists(site.Config.AbsoluteSiteDir) &&
+            Directory.EnumerateFiles(site.Config.AbsoluteSiteDir, "*", SearchOption.AllDirectories).Any());
+    }
+
+    [Fact]
+    public async Task SlugifyRedirect_ArrayOfConfigs_AllApplied()
+    {
+        var site = Site();
+        site.Pages.Add(new Page { SourcePath = "x", RelativePath = "x.md", Url = "posts/my-post/" });
+        var plugin = new RedirectsPlugin();
+        plugin.Configure(new FakeContext(
+            new Dictionary<string, object?>
+            {
+                ["slugify_redirects"] = new List<object?>
+                {
+                    new Dictionary<string, object?> { ["separator"] = "_" },
+                    new Dictionary<string, object?> { ["separator"] = "+" },
+                },
+            },
+            site.Config));
+        await plugin.OnBuildCompleteAsync(site, default);
+
+        Assert.Contains("url=/posts/my-post/", ReadStub(site, "posts/my_post/index.html"));
+        Assert.Contains("url=/posts/my-post/", ReadStub(site, "posts/my+post/index.html"));
+    }
+
+    [Fact]
+    public async Task SlugifyRedirect_DoesNotClobberExistingPage()
+    {
+        var site = Site();
+        // Current page whose old-separator slug would collide with a real page below.
+        site.Pages.Add(new Page { SourcePath = "a", RelativePath = "a.md", Url = "a-b/" });
+        // A real page already living at the would-be old URL.
+        site.Pages.Add(new Page { SourcePath = "b", RelativePath = "b.md", Url = "a_b/" });
+        var plugin = new RedirectsPlugin();
+        plugin.Configure(new FakeContext(
+            new Dictionary<string, object?>
+            {
+                ["slugify_redirects"] = new Dictionary<string, object?> { ["separator"] = "_" },
+            },
+            site.Config));
+        await plugin.OnBuildCompleteAsync(site, default);
+
+        // No stub should be written over the real /a_b/ page.
+        Assert.False(File.Exists(Path.Combine(site.Config.AbsoluteSiteDir, "a_b", "index.html")));
+    }
+
+    [Fact]
+    public async Task SlugifyRedirect_ConfiguredMapOverridesGeneratedSource()
+    {
+        var site = Site();
+        site.Pages.Add(new Page { SourcePath = "x", RelativePath = "x.md", Url = "blog/ls-how-to/" });
+        var plugin = new RedirectsPlugin();
+        plugin.Configure(new FakeContext(
+            new Dictionary<string, object?>
+            {
+                ["slugify_redirects"] = new Dictionary<string, object?> { ["separator"] = "_" },
+                // An explicit map for the same generated source must win.
+                ["redirect_maps"] = new Dictionary<string, object?> { ["blog/ls_how_to/"] = "/somewhere-else/" },
+            },
+            site.Config));
+        await plugin.OnBuildCompleteAsync(site, default);
+
+        Assert.Contains("url=/somewhere-else/", ReadStub(site, "blog/ls_how_to/index.html"));
+    }
+
     private sealed class FakeContext(IReadOnlyDictionary<string, object?> options, SiteConfig config) : IPluginContext
     {
         public SiteConfig Config { get; } = config;
