Improve markdown local file link resolution

Author: xoofx

site/docs/controls/markdowncontrol.md

@@ -61,6 +61,20 @@ var control = new MarkdownControl(markdown)
 };
 ```
 
+For Markdown documents that contain local file links, use `LocalFileRootPath` to resolve relative paths into valid local `file://` URIs:
+
+```csharp
+var control = new MarkdownControl(markdown)
+{
+    Options = MarkdownRenderOptions.Default with
+    {
+        LocalFileRootPath = Environment.CurrentDirectory,
+    }
+};
+```
+
+Absolute local paths such as `C:\docs\guide.md` on Windows are also normalized to `file://` links automatically.
+
 Spacing defaults are intentionally compact for terminal density:
 
 - heading spacing before: `0`

site/docs/specs/controls/markdowncontrol.md

@@ -248,6 +248,8 @@ Runs MUST be merged when adjacent and identical to reduce allocations.
 - Use `HyperlinkRun(start, length, uri)` on the rendered text span.
 - Apply a link style run (underline + optional accent).
 - Resolve relative URIs against `BaseUri` when provided.
+- Absolute local file paths SHOULD be normalized to `file://` URIs.
+- Relative local file links MAY be resolved against `MarkdownRenderOptions.LocalFileRootPath` when provided. This local file root takes precedence over `BaseUri` for non-absolute, non-fragment links.
 
 Images:
 
@@ -383,4 +385,3 @@ Add a `ControlsDemo` page:
   - link styling,
   - different table presets,
   - alert styles.
-

src/XenoAtom.Terminal.UI.Extensions.Markdown/MarkdownDocumentBuilder.cs

@@ -2,6 +2,7 @@
 // Licensed under the BSD-Clause 2 license.
 // See license.txt file in the project root for full license information.
 
+using System.IO;
 using System.Text;
 using Markdig.Extensions.Alerts;
 using Markdig.Extensions.Tables;
@@ -23,6 +24,7 @@ internal sealed class MarkdownDocumentBuilder
     private readonly MarkdownStyle _style;
     private readonly MarkdownRenderOptions _options;
     private readonly Uri? _baseUri;
+    private readonly string? _localFileRootPath;
     private readonly List<DocumentFlowBlock> _blocks;
     private readonly int _headingSpacingBefore;
     private readonly int _headingSpacingAfter;
@@ -36,6 +38,7 @@ public MarkdownDocumentBuilder(MarkdownStyle style, MarkdownRenderOptions option
         _style = style;
         _options = options;
         _baseUri = baseUri;
+        _localFileRootPath = NormalizeLocalFileRootPath(options.LocalFileRootPath);
         _blocks = new List<DocumentFlowBlock>(64);
         _headingSpacingBefore = Math.Max(0, _options.HeadingSpacingBefore);
         _headingSpacingAfter = Math.Max(0, _options.HeadingSpacingAfter);
@@ -711,17 +714,179 @@ private static string ExtractInlinePlainText(ContainerInline inline)
             return null;
         }
 
-        if (Uri.TryCreate(link, UriKind.Absolute, out var absolute))
+        var trimmed = link.Trim();
+
+        if (TryResolveLocalFileUri(trimmed, out var localFileUri))
+        {
+            return localFileUri;
+        }
+
+        if (Uri.TryCreate(trimmed, UriKind.Absolute, out var absolute))
         {
             return absolute.ToString();
         }
 
-        if (_baseUri is not null && Uri.TryCreate(_baseUri, link, out var relative))
+        if (_baseUri is not null && Uri.TryCreate(_baseUri, trimmed, out var relative))
         {
             return relative.ToString();
         }
 
-        return link;
+        return trimmed;
+    }
+
+    private bool TryResolveLocalFileUri(string link, out string? uri)
+    {
+        uri = null;
+        if (IsFragmentOrQueryOnly(link))
+        {
+            return false;
+        }
+
+        if (TryResolveAbsoluteLocalFileUri(link, out uri))
+        {
+            return true;
+        }
+
+        if (_localFileRootPath is null)
+        {
+            return false;
+        }
+
+        SplitPathAndSuffix(link, out var pathPart, out var suffix);
+        if (string.IsNullOrWhiteSpace(pathPart))
+        {
+            return false;
+        }
+
+        var normalizedRelativePath = NormalizeRelativeFilePath(pathPart);
+        var combinedPath = Path.GetFullPath(Path.Combine(_localFileRootPath, normalizedRelativePath));
+        uri = CreateFileUri(combinedPath, suffix);
+        return true;
+    }
+
+    private static string? NormalizeLocalFileRootPath(string? rootPath)
+    {
+        if (string.IsNullOrWhiteSpace(rootPath))
+        {
+            return null;
+        }
+
+        return Path.GetFullPath(rootPath);
+    }
+
+    private static bool TryResolveAbsoluteLocalFileUri(string link, out string? uri)
+    {
+        SplitPathAndSuffix(link, out var pathPart, out var suffix);
+
+        if (IsWindowsDrivePath(pathPart))
+        {
+            uri = CreateFileUri(pathPart.Replace('/', '\\'), suffix);
+            return true;
+        }
+
+        if (IsWindowsUncPath(pathPart))
+        {
+            uri = CreateFileUri(pathPart, suffix);
+            return true;
+        }
+
+        if (IsUnixAbsolutePath(pathPart))
+        {
+            uri = CreateFileUri(pathPart, suffix);
+            return true;
+        }
+
+        uri = null;
+        return false;
+    }
+
+    private static bool IsWindowsDrivePath(string path)
+    {
+        return path.Length >= 3
+            && IsAsciiLetter(path[0])
+            && path[1] == ':'
+            && IsDirectorySeparator(path[2]);
+    }
+
+    private static bool IsWindowsUncPath(string path)
+    {
+        return path.Length >= 2 && path[0] == '\\' && path[1] == '\\';
+    }
+
+    private static bool IsUnixAbsolutePath(string path)
+    {
+        return !OperatingSystem.IsWindows() && path.Length > 0 && path[0] == '/';
+    }
+
+    private static bool IsAsciiLetter(char c)
+    {
+        c = char.ToUpperInvariant(c);
+        return c >= 'A' && c <= 'Z';
+    }
+
+    private static bool IsDirectorySeparator(char c) => c is '\\' or '/';
+
+    private static bool IsFragmentOrQueryOnly(string link) => link.Length > 0 && link[0] is '#' or '?';
+
+    private static string NormalizeRelativeFilePath(string path)
+    {
+        var normalized = path;
+        if (Path.DirectorySeparatorChar == '\\')
+        {
+            normalized = normalized.Replace('/', '\\');
+        }
+        else
+        {
+            normalized = normalized.Replace('\\', '/');
+        }
+
+        return normalized.Replace(Path.AltDirectorySeparatorChar, Path.DirectorySeparatorChar);
+    }
+
+    private static void SplitPathAndSuffix(string link, out string pathPart, out string suffix)
+    {
+        var queryIndex = link.IndexOf('?');
+        var fragmentIndex = link.IndexOf('#');
+
+        var suffixIndex = -1;
+        if (queryIndex >= 0 && fragmentIndex >= 0)
+        {
+            suffixIndex = Math.Min(queryIndex, fragmentIndex);
+        }
+        else if (queryIndex >= 0)
+        {
+            suffixIndex = queryIndex;
+        }
+        else if (fragmentIndex >= 0)
+        {
+            suffixIndex = fragmentIndex;
+        }
+
+        if (suffixIndex < 0)
+        {
+            pathPart = link;
+            suffix = string.Empty;
+            return;
+        }
+
+        pathPart = link[..suffixIndex];
+        suffix = link[suffixIndex..];
+    }
+
+    private static string CreateFileUri(string path, string suffix)
+    {
+        var fileUri = new UriBuilder(Uri.UriSchemeFile, string.Empty, -1, path).Uri;
+        if (string.IsNullOrEmpty(suffix))
+        {
+            return fileUri.AbsoluteUri;
+        }
+
+        if (Uri.TryCreate(fileUri, suffix, out var resolved))
+        {
+            return resolved.AbsoluteUri;
+        }
+
+        return string.Concat(fileUri.AbsoluteUri, suffix);
     }
 
     private readonly record struct InlineRenderResult(string Text, StyledRun[] Runs, HyperlinkRun[] Hyperlinks);

src/XenoAtom.Terminal.UI.Extensions.Markdown/MarkdownRenderOptions.cs

@@ -2,6 +2,7 @@
 // Licensed under the BSD-Clause 2 license.
 // See license.txt file in the project root for full license information.
 
+using XenoAtom.Terminal.UI.Controls;
 using XenoAtom.Terminal.UI.Styling;
 
 namespace XenoAtom.Terminal.UI.Extensions.Markdown;
@@ -46,6 +47,16 @@ public sealed record MarkdownRenderOptions
     /// </summary>
     public bool RenderImagesAsLinks { get; init; } = true;
 
+    /// <summary>
+    /// Gets an optional local file-system root path used to resolve relative Markdown links into <c>file://</c> URIs.
+    /// </summary>
+    /// <remarks>
+    /// When specified, non-absolute links that are not pure fragment/query references are combined with this root path
+    /// before <see cref="MarkdownControl.BaseUri"/> is considered. Use this when Markdown documents contain local relative
+    /// file references instead of web-relative links.
+    /// </remarks>
+    public string? LocalFileRootPath { get; init; }
+
     /// <summary>
     /// Gets the default table style for Markdown tables.
     /// </summary>

src/XenoAtom.Terminal.UI.Extensions.Markdown/readme.md

@@ -24,6 +24,18 @@ Paragraph with **bold** text and [a link](https://example.com).
 var control = new MarkdownControl(markdown);
 ```
 
+Resolve relative file links locally while still supporting standard web `BaseUri` resolution:
+
+```csharp
+var control = new MarkdownControl(markdown)
+{
+    Options = MarkdownRenderOptions.Default with
+    {
+        LocalFileRootPath = Environment.CurrentDirectory,
+    },
+};
+```
+
 Convert interpreted markdown into markup:
 
 ```csharp
@@ -44,7 +56,7 @@ var runs = converter.Highlight(markdown); // StyledRun[] over the original markd
 
 - CommonMark block and inline rendering.
 - Extensions enabled by default: pipe tables and alert blocks.
-- `MarkdownRenderOptions` for code block wrapping/height, compact spacing, and HTML/image fallbacks.
+- `MarkdownRenderOptions` for code block wrapping/height, compact spacing, HTML/image fallbacks, and local file-link resolution.
 - Theme-aware pleasant defaults (bright-yellow headings, accent strong text, bright-red inline code, semantic alerts).
 - `MarkdownStyle` for heading/link/emphasis/alert style customization.
 - `MarkdownDocumentContent` for direct usage with `DocumentFlow` feeds.

src/XenoAtom.Terminal.UI.Tests/MarkdownControlTests.cs

@@ -2,6 +2,7 @@
 // Licensed under the BSD-Clause 2 license.
 // See license.txt file in the project root for full license information.
 
+using System.IO;
 using XenoAtom.Terminal.UI.Controls;
 using XenoAtom.Terminal.UI.Extensions.Markdown;
 using XenoAtom.Terminal.UI.Extensions.Markdown.Styling;
@@ -320,6 +321,54 @@ public void MarkdownControl_Resolves_Relative_Links_With_BaseUri()
         Assert.AreEqual("https://example.com/docs/guide/readme.md", paragraph.Hyperlinks[0].Uri);
     }
 
+    [TestMethod]
+    public void MarkdownControl_Converts_Absolute_Windows_File_Links_To_FileUris()
+    {
+        const string path = @"C:\docs\guide.md";
+        var control = new MarkdownControl($"See [docs]({path}).");
+
+        var paragraph = GetParagraph(control, 0);
+        Assert.AreEqual(1, paragraph.Hyperlinks.Length);
+        Assert.AreEqual(CreateExpectedFileUri(path), paragraph.Hyperlinks[0].Uri);
+    }
+
+    [TestMethod]
+    public void MarkdownControl_Resolves_Relative_File_Links_With_LocalFileRootPath()
+    {
+        var localRoot = Path.Combine(Path.GetTempPath(), "markdown-local-root");
+        var control = new MarkdownControl("See [docs](guide/readme.md).")
+        {
+            BaseUri = new Uri("https://example.com/docs/"),
+            Options = MarkdownRenderOptions.Default with
+            {
+                LocalFileRootPath = localRoot,
+            },
+        };
+
+        var paragraph = GetParagraph(control, 0);
+        Assert.AreEqual(1, paragraph.Hyperlinks.Length);
+        Assert.AreEqual(
+            CreateExpectedFileUri(Path.GetFullPath(Path.Combine(localRoot, "guide", "readme.md"))),
+            paragraph.Hyperlinks[0].Uri);
+    }
+
+    [TestMethod]
+    public void MarkdownControl_Keeps_Fragment_Links_Resolvable_With_BaseUri_When_LocalFileRootPath_Is_Set()
+    {
+        var control = new MarkdownControl("See [section](#intro).")
+        {
+            BaseUri = new Uri("https://example.com/docs/page.md"),
+            Options = MarkdownRenderOptions.Default with
+            {
+                LocalFileRootPath = Path.Combine(Path.GetTempPath(), "markdown-local-root"),
+            },
+        };
+
+        var paragraph = GetParagraph(control, 0);
+        Assert.AreEqual(1, paragraph.Hyperlinks.Length);
+        Assert.AreEqual("https://example.com/docs/page.md#intro", paragraph.Hyperlinks[0].Uri);
+    }
+
     [TestMethod]
     public void MarkdownControl_Renders_Images_As_Link_Placeholders()
     {
@@ -851,4 +900,9 @@ private static bool IsLightTheme(Theme theme)
         var foregroundLuminance = foreground.GetRelativeLuminance();
         return backgroundLuminance > foregroundLuminance && backgroundLuminance >= 0.55f;
     }
+
+    private static string CreateExpectedFileUri(string path)
+    {
+        return new UriBuilder(Uri.UriSchemeFile, string.Empty, -1, path).Uri.AbsoluteUri;
+    }
 }