fix(links): preserve custom URI schemes and dots in slugified URLs

Two link-correctness issues surfaced by a docs-parity audit:

1. Custom-scheme links (e.g. `vscode:extension/ms-python.python`, `tel:`)
   were mangled into relative resource links because the rewriter only
   treated `://` URLs as external. Replace the ad-hoc scheme checks with a
   single URI-scheme detector so any `scheme:` link is left untouched.

2. slugify.urls dropped dots entirely, so `2025.05.05` date/version
   segments became `20250505`. Periods are URL-safe and appear in dates and
   version numbers, so keep them: Slug.Make gains an optional `keep` set and
   UrlFor preserves `.` when slugifying content URL segments.

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

Author: Netdocs

src/Netdocs.Abstractions/Slug.cs

@@ -10,8 +10,12 @@ public static class Slug
     public static string Make(string text, string separator = "-") =>
         Make(text, new SlugifyConfig { Separator = separator });
 
-    /// <summary>Slugify honoring a <see cref="SlugifyConfig"/> (case, separator, ASCII folding).</summary>
-    public static string Make(string text, SlugifyConfig config)
+    /// <summary>Slugify honoring a <see cref="SlugifyConfig"/> (case, separator, ASCII folding).
+    /// Characters listed in <paramref name="keep"/> are preserved verbatim instead of being
+    /// dropped — used by URL slugification to retain URL-safe punctuation such as <c>.</c>
+    /// (so e.g. a <c>2025.05.05</c> date segment stays intact rather than becoming
+    /// <c>20250505</c>).</summary>
+    public static string Make(string text, SlugifyConfig config, string keep = "")
     {
         var normalized = text.Normalize(NormalizationForm.FormD);
         var sb = new StringBuilder(normalized.Length);
@@ -25,6 +29,10 @@ public static string Make(string text, SlugifyConfig config)
                 if (config.Ascii && c > 127) continue; // drop non-ASCII letters/digits when ASCII-only
                 sb.Append(ApplyCase(c, config.Case));
             }
+            else if (keep.Length > 0 && keep.IndexOf(c) >= 0)
+            {
+                sb.Append(c);
+            }
             else if (char.IsWhiteSpace(c) || c is '-' or '_' or '/')
             {
                 sb.Append(' ');

src/Netdocs.Core/Content/ContentDiscovery.cs

@@ -84,7 +84,7 @@ public static string UrlFor(string relative, SlugifyConfig? slugify = null)
 
         var urlSegments = isIndex ? segments[..^1] : segments;
         if (slugify is not null)
-            urlSegments = [.. urlSegments.Select(s => Slug.Make(s, slugify))];
+            urlSegments = [.. urlSegments.Select(s => Slug.Make(s, slugify, "."))];
 
         var dir = string.Join('/', urlSegments);
         return dir.Length == 0 ? "" : dir + "/";

src/Netdocs.Core/Markdown/DocumentRenderer.cs

@@ -1,4 +1,5 @@
 using System.Text;
+using System.Text.RegularExpressions;
 using AngleSharp.Html.Parser;
 using Markdig;
 using Markdig.Renderers;
@@ -10,13 +11,24 @@
 namespace Netdocs.Core.Markdown;
 
 /// <summary>Renders processed markdown to HTML and extracts TOC, title, and plain text.</summary>
-public sealed class DocumentRenderer(
+public sealed partial class DocumentRenderer(
     MarkdownPipeline pipeline,
     IReadOnlyDictionary<string, string>? linkMap = null,
     bool abbreviationsFirstInstanceOnly = false)
 {
     private readonly HtmlParser _htmlParser = new();
 
+    // Matches a URI scheme prefix (e.g. `http:`, `mailto:`, `data:`, `vscode:`, `tel:`).
+    // Custom schemes like `vscode:extension/...` have no `//`, so a bare `://` check misses
+    // them; anything with a scheme must be left untouched, not treated as a relative path.
+    [GeneratedRegex(@"^[a-zA-Z][a-zA-Z0-9+.\-]*:", RegexOptions.CultureInvariant)]
+    private static partial Regex UriSchemeRegex();
+
+    /// <summary>True when a link is absolute (root-relative), an in-page anchor, or carries a
+    /// URI scheme — i.e. it must not be rewritten as a page/resource-relative link.</summary>
+    internal static bool IsAbsoluteOrExternal(string url) =>
+        url.StartsWith('/') || url.StartsWith('#') || UriSchemeRegex().IsMatch(url);
+
     public void Render(Page page)
     {
         var document = Markdig.Markdown.Parse(page.ProcessedMarkdown, pipeline);
@@ -73,9 +85,7 @@ private void RewriteMarkdownLinks(MarkdownDocument document, string currentRelat
     /// (no leading slash; callers prepend a base-relative prefix).</summary>
     internal static string? ResolveResourceLink(string currentRelativePath, string url, bool isImage)
     {
-        if (url.Contains("://") || url.StartsWith('/') || url.StartsWith('#') ||
-            url.StartsWith("mailto:", StringComparison.OrdinalIgnoreCase) ||
-            url.StartsWith("data:", StringComparison.OrdinalIgnoreCase))
+        if (IsAbsoluteOrExternal(url))
             return null;
 
         var cut = url.IndexOfAny(['#', '?']);
@@ -99,8 +109,7 @@ private void RewriteMarkdownLinks(MarkdownDocument document, string currentRelat
 
     internal static string? ResolveMarkdownLink(string currentRelativePath, string url, IReadOnlyDictionary<string, string> map)
     {
-        if (url.Contains("://") || url.StartsWith('/') || url.StartsWith('#') ||
-            url.StartsWith("mailto:", StringComparison.OrdinalIgnoreCase))
+        if (IsAbsoluteOrExternal(url))
             return null;
 
         var hash = url.IndexOf('#');

tests/Netdocs.Core.Tests/CoreTests.cs

@@ -24,6 +24,8 @@ public void UrlFor_ProducesDirectoryUrls(string relative, string expected)
     [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/")]
+    [InlineData("changelogs/2025/Q2/2025.05.05.md", "changelogs/2025/q2/2025.05.05/")]
+    [InlineData("releases/v1.2.3 Notes.md", "releases/v1.2.3-notes/")]
     public void UrlFor_WithSlugify_SlugifiesSegments(string relative, string expected)
         => Assert.Equal(expected, ContentDiscovery.UrlFor(relative, new SlugifyConfig()));
 
@@ -394,4 +396,27 @@ public void MarkdownLinks_WithPercentEncodedSpaces_ResolveToSlugifiedTarget()
         Assert.Contains("href=\"../../cluster/openshift-registry-setup/\"", page.HtmlContent);
         Assert.DoesNotContain("%20", page.HtmlContent);
     }
+
+    [Theory]
+    [InlineData("vscode:extension/ms-python.python")]
+    [InlineData("mailto:team@example.com")]
+    [InlineData("tel:+15551234567")]
+    [InlineData("https://example.com/docs.md")]
+    public void CustomSchemeLinks_AreLeftUntouched(string url)
+    {
+        // Links carrying any URI scheme (not just `://` ones) must not be rewritten as
+        // relative page/resource links. Regression guard for `vscode:extension/...` deep links.
+        var site = new SiteContext { Config = new SiteConfig(), Options = new BuildOptions(), LoggerFactory = NullLoggerFactory.Instance };
+        var pipeline = MarkdownPipelineFactory.Build(site, []);
+        var page = new Page
+        {
+            SourcePath = "tools/guide.md",
+            RelativePath = "tools/guide.md",
+            Url = "tools/guide/",
+            ProcessedMarkdown = $"Install [it]({url}).",
+        };
+        new DocumentRenderer(pipeline, new Dictionary<string, string>()).Render(page);
+
+        Assert.Contains($"href=\"{url}\"", page.HtmlContent);
+    }
 }