feat(urls): add opt-in slugify for content page URLs

Content files previously mapped to URLs mirroring their filenames verbatim,
so names with spaces produced percent-encoded paths (e.g.
`Openshift Registry Setup/` -> `Openshift%20Registry%20Setup/`). Some static
hosts (notably S3 + CloudFront) fail to resolve those `%20` paths and 404.

Add a `slugify.urls` toggle (default off, mkdocs-compatible) that slugifies
each content URL path segment using the existing `case`/`separator`/`ascii`
settings. Internal `.md` links are rewritten to the slugified targets
automatically via the existing link map (keyed on real paths, valued on URLs).

Move the `Slug` helper from Netdocs.Plugins to Netdocs.Abstractions so the
core content discovery can reuse it.

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

Author: Netdocs

docs-site/docs/reference/configuration.md

@@ -113,10 +113,36 @@ produced by a configurable slugifier. Add a `slugify` block to control it:
 | `case` | `lower` | Letter casing: `lower`, `upper`, or `none` (preserve). |
 | `separator` | `-` | String inserted between words (e.g. `_` or `.`). |
 | `ascii` | `false` | When `true`, drop non-ASCII letters/digits instead of keeping them. |
+| `urls` | `false` | When `true`, slugify **content page URLs** too (see below). |
 
 With the defaults, `"Hello World!"` becomes `hello-world`. Set `"separator": "_"` to get
 `hello_world`, or `"case": "none"` to keep the original casing.
 
+### Slugifying content URLs
+
+By default a content file maps to a URL that mirrors its path exactly, so
+`Openshift Registry Setup.md` becomes `Openshift%20Registry%20Setup/`. Spaces (and other
+characters that must be percent-encoded) can trip up static hosts — for example an S3 +
+CloudFront site may fail to resolve `%20` paths and return `404`.
+
+Set `"urls": true` to slugify every path segment of content URLs using the same `case`,
+`separator`, and `ascii` rules:
+
+```json
+{
+  "Netdocs": {
+    "slugify": {
+      "urls": true
+    }
+  }
+}
+```
+
+With this enabled, `docs/cluster-setup/Openshift Registry Setup.md` is published at
+`cluster-setup/openshift-registry-setup/`. Internal `*.md` links are rewritten to the
+slugified targets automatically, so cross-page links keep working. Leaving `urls` off (the
+default) preserves mkdocs-compatible, filename-based URLs.
+
 ## Deployment
 
 A `deploy` block tells `netdocs deploy` where to publish the built site. See

src/Netdocs.Abstractions/SiteConfig.cs

@@ -43,6 +43,14 @@ public sealed class SiteConfig
     /// <summary>Controls how titles/ids are turned into URL slugs (blog, categories, authors, tags).</summary>
     public SlugifyConfig Slugify { get; set; } = new();
 
+    /// <summary>When true, slugify content file paths into their output URLs (e.g.
+    /// <c>Openshift Registry Setup.md</c> → <c>openshift-registry-setup/</c>) using the
+    /// <see cref="Slugify"/> settings. Off by default to keep URLs identical to source
+    /// filenames (mkdocs-compatible). Turn on to guarantee clean, space-free URLs that
+    /// static hosts (S3/CloudFront) can serve without percent-encoding issues. Internal
+    /// <c>.md</c> links are rewritten to the slugified targets automatically.</summary>
+    public bool SlugifyUrls { get; set; }
+
     /// <summary>Behaviour of the abbreviations feature (<c>&lt;abbr&gt;</c> tooltips).</summary>
     public AbbreviationsConfig Abbreviations { get; set; } = new();
 

src/Netdocs.Plugins/Slug.cs src/Netdocs.Abstractions/Slug.cssrc/Netdocs.Plugins/Slug.cs renamed to src/Netdocs.Abstractions/Slug.cs

@@ -1,8 +1,7 @@
 using System.Globalization;
 using System.Text;
-using Netdocs.Abstractions;
 
-namespace Netdocs.Plugins;
+namespace Netdocs.Abstractions;
 
 /// <summary>Slugifies text for URLs. Default: lowercase, hyphen-separated, accents folded.</summary>
 public static class Slug

src/Netdocs.Core/Configuration/JsonConfigLoader.cs

@@ -41,6 +41,7 @@ public static SiteConfig Load(string appSettingsPath)
             Exclude = StringList(root.Get("exclude")),
             Extra = root.Get("extra").AsMap(),
             Slugify = ParseSlugify(root.Get("slugify").AsMap()),
+            SlugifyUrls = root.Get("slugify").AsMap().Get("urls").AsBool(false),
             Deploy = ParseDeploy(root.Get("deploy").AsMap()),
             Optimize = ParseOptimize(root.Get("optimize").AsMap()),
             Validation = ParseValidation(root.Get("validation").AsMap()),

src/Netdocs.Core/Content/ContentDiscovery.cs

@@ -46,7 +46,7 @@ private Page LoadPage(string absolutePath, string relative)
         var raw = File.ReadAllText(absolutePath);
         var (meta, body) = FrontMatter.Split(raw);
 
-        var url = UrlFor(relative);
+        var url = UrlFor(relative, config.SlugifyUrls ? config.Slugify : null);
         var page = new Page
         {
             SourcePath = absolutePath,
@@ -70,18 +70,24 @@ private Page LoadPage(string absolutePath, string relative)
         return page;
     }
 
-    /// <summary>Directory-style URLs: foo/bar.md -> foo/bar/ ; index.md -> its dir.</summary>
-    public static string UrlFor(string relative)
+    /// <summary>Directory-style URLs: foo/bar.md -> foo/bar/ ; index.md -> its dir.
+    /// When <paramref name="slugify"/> is supplied, each path segment is slugified
+    /// (e.g. <c>Openshift Registry Setup.md</c> -> <c>openshift-registry-setup/</c>) so the
+    /// resulting URL is free of spaces and other characters that static hosts must
+    /// percent-encode.</summary>
+    public static string UrlFor(string relative, SlugifyConfig? slugify = null)
     {
         var withoutExt = relative[..^Path.GetExtension(relative).Length];
         var segments = withoutExt.Split('/');
-        if (segments[^1].Equals("index", StringComparison.OrdinalIgnoreCase)
-            || segments[^1].Equals("README", StringComparison.OrdinalIgnoreCase))
-        {
-            var dir = string.Join('/', segments[..^1]);
-            return dir.Length == 0 ? "" : dir + "/";
-        }
-        return withoutExt + "/";
+        var isIndex = segments[^1].Equals("index", StringComparison.OrdinalIgnoreCase)
+            || segments[^1].Equals("README", StringComparison.OrdinalIgnoreCase);
+
+        var urlSegments = isIndex ? segments[..^1] : segments;
+        if (slugify is not null)
+            urlSegments = [.. urlSegments.Select(s => Slug.Make(s, slugify))];
+
+        var dir = string.Join('/', urlSegments);
+        return dir.Length == 0 ? "" : dir + "/";
     }
 
     public static string OutputFileFor(string url)

tests/Netdocs.Core.Tests/CoreTests.cs

@@ -18,6 +18,23 @@ public class UrlTests
     public void UrlFor_ProducesDirectoryUrls(string relative, string expected)
         => Assert.Equal(expected, ContentDiscovery.UrlFor(relative));
 
+    [Theory]
+    [InlineData("index.md", "")]
+    [InlineData("Openshift Registry Setup.md", "openshift-registry-setup/")]
+    [InlineData("cluster-setup/Deploying MetalLB.md", "cluster-setup/deploying-metallb/")]
+    [InlineData("Applications/Kubernetes/index.md", "applications/kubernetes/")]
+    [InlineData("Guide_One/Step Two.md", "guide-one/step-two/")]
+    public void UrlFor_WithSlugify_SlugifiesSegments(string relative, string expected)
+        => Assert.Equal(expected, ContentDiscovery.UrlFor(relative, new SlugifyConfig()));
+
+    [Fact]
+    public void UrlFor_WithSlugify_HonorsCaseAndSeparator()
+        => Assert.Equal(
+            "Openshift_Registry_Setup/",
+            ContentDiscovery.UrlFor(
+                "Openshift Registry Setup.md",
+                new SlugifyConfig { Case = "none", Separator = "_" }));
+
     [Theory]
     [InlineData("", "")]
     [InlineData("about/", "../")]

tests/Netdocs.Core.Tests/SlugTests.cs

@@ -1,5 +1,4 @@
 using Netdocs.Abstractions;
-using Netdocs.Plugins;
 using Xunit;
 
 namespace Netdocs.Core.Tests;