feat: Implement asset-aware structures for markdown processing with link detection and resolution

Author: Arlodotexe

src/Blog/Assets/IAssetInclusionStrategy.cs

@@ -0,0 +1,30 @@
+using OwlCore.Storage;
+
+namespace WindowsAppCommunity.Blog.Assets;
+
+/// <summary>
+/// Provides decision logic for asset inclusion via path rewriting.
+/// Strategy returns rewritten path - path structure determines Include vs Reference behavior.
+/// </summary>
+public interface IAssetInclusionStrategy
+{
+    /// <summary>
+    /// Decides asset inclusion strategy by returning rewritten path.
+    /// </summary>
+    /// <param name="referencingMarkdown">The markdown file that references the asset.</param>
+    /// <param name="referencedAsset">The asset file being referenced.</param>
+    /// <param name="originalPath">The original relative path from markdown.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>
+    /// Rewritten path string. Path structure determines behavior:
+    /// <list type="bullet">
+    /// <item><description>Child path (no ../ prefix): Asset included in page folder (self-contained)</description></item>
+    /// <item><description>Parent path (../ prefix): Asset referenced externally (link rewritten to account for folderization)</description></item>
+    /// </list>
+    /// </returns>
+    Task<string> DecideAsync(
+        IFile referencingMarkdown,
+        IFile referencedAsset,
+        string originalPath,
+        CancellationToken ct = default);
+}

src/Blog/Assets/IAssetLinkDetector.cs

@@ -0,0 +1,17 @@
+using OwlCore.Storage;
+
+namespace WindowsAppCommunity.Blog.Assets;
+
+/// <summary>
+/// Detects relative asset links in rendered HTML output.
+/// </summary>
+public interface IAssetLinkDetector
+{
+    /// <summary>
+    /// Detects relative asset link strings in rendered HTML output.
+    /// </summary>
+    /// <param name="htmlSource">Virtual IFile representing rendered HTML output (in-memory representation).</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>Async enumerable of relative path strings.</returns>
+    IAsyncEnumerable<string> DetectAsync(IFile htmlSource, CancellationToken ct = default);
+}

src/Blog/Assets/IAssetResolver.cs

@@ -0,0 +1,27 @@
+using OwlCore.Storage;
+
+namespace WindowsAppCommunity.Blog.Assets;
+
+/// <summary>
+/// Resolves relative path strings to IFile instances.
+/// </summary>
+public interface IAssetResolver
+{
+    /// <summary>
+    /// Root folder for relative path resolution.
+    /// </summary>
+    IFolder SourceFolder { get; init; }
+
+    /// <summary>
+    /// Markdown file for relative path context.
+    /// </summary>
+    IFile MarkdownSource { get; init; }
+
+    /// <summary>
+    /// Resolves a relative path string to an IFile instance.
+    /// </summary>
+    /// <param name="relativePath">The relative path to resolve.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>The resolved IFile, or null if not found.</returns>
+    Task<IFile?> ResolveAsync(string relativePath, CancellationToken ct = default);
+}

src/Blog/Page/AssetAwareHtmlTemplatedMarkdownFile.cs

@@ -0,0 +1,109 @@
+using System;
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+using OwlCore.Storage;
+using WindowsAppCommunity.Blog.Assets;
+using WindowsAppCommunity.Blog.PostPage;
+
+namespace WindowsAppCommunity.Blog.Page
+{
+    /// <summary>
+    /// Asset-aware virtual HTML file - extends base with link detection, asset resolution, and inclusion decisions.
+    /// Sealed - this is the final asset-aware implementation.
+    /// Implements link rewriting and asset tracking during post-processing.
+    /// </summary>
+    public sealed class AssetAwareHtmlTemplatedMarkdownFile : HtmlTemplatedMarkdownFile
+    {
+        private readonly List<IFile> _includedAssets = new();
+
+        /// <summary>
+        /// Creates asset-aware virtual HTML file with lazy markdown→HTML generation and asset management.
+        /// </summary>
+        /// <param name="id">Unique identifier for this file (parent-derived)</param>
+        /// <param name="markdownSource">Source markdown file to transform</param>
+        /// <param name="templateSource">Template as IFile or IFolder</param>
+        /// <param name="templateFileName">Template file name when source is IFolder (defaults to "template.html")</param>
+        /// <param name="parent">Parent folder in virtual hierarchy (optional)</param>
+        public AssetAwareHtmlTemplatedMarkdownFile(
+            string id, 
+            IFile markdownSource, 
+            IStorable templateSource, 
+            string? templateFileName = null, 
+            IFolder? parent = null)
+            : base(id, markdownSource, templateSource, templateFileName, parent)
+        {
+        }
+
+        /// <summary>
+        /// Asset link detector for finding relative links in rendered HTML output.
+        /// </summary>
+        public required IAssetLinkDetector LinkDetector { get; init; }
+
+        /// <summary>
+        /// Asset resolver for converting paths to IFile instances.
+        /// </summary>
+        public required IAssetResolver Resolver { get; init; }
+
+        /// <summary>
+        /// Inclusion strategy for deciding include vs reference via path rewriting.
+        /// </summary>
+        public required IAssetInclusionStrategy InclusionStrategy { get; init; }
+
+        /// <summary>
+        /// Assets that were decided for inclusion (self-contained in page folder).
+        /// Exposed to containing folder for yielding in virtual structure.
+        /// </summary>
+        public IReadOnlyCollection<IFile> IncludedAssets => _includedAssets.AsReadOnly();
+
+        /// <summary>
+        /// Post-process HTML with asset management pipeline.
+        /// Detects links → Resolves to files → Decides include/reference via path rewriting → Tracks included assets.
+        /// </summary>
+        /// <param name="html">Rendered HTML from template</param>
+        /// <param name="model">Data model used for rendering</param>
+        /// <param name="ct">Cancellation token</param>
+        /// <returns>Post-processed HTML with rewritten links</returns>
+        protected override async Task<string> PostProcessHtmlAsync(string html, PostPageDataModel model, CancellationToken ct)
+        {
+            // Clear included assets from any previous generation
+            _includedAssets.Clear();
+
+            // Detect asset links in rendered HTML output (pass self as IFile)
+            await foreach (var originalPath in LinkDetector.DetectAsync(this, ct))
+            {
+                // Resolve path to IFile
+                var resolvedAsset = await Resolver.ResolveAsync(originalPath, ct);
+
+                // Null resolver policy: Skip if not found (preserve broken link)
+                if (resolvedAsset == null)
+                {
+                    continue;
+                }
+
+                // Strategy decides include vs reference by returning rewritten path
+                // Path structure determines behavior:
+                // - Child path (no ../ prefix): Include
+                // - Parent path (../ prefix): Reference
+                var rewrittenPath = await InclusionStrategy.DecideAsync(
+                    MarkdownSource,  // Pass original markdown source (not virtual HTML)
+                    resolvedAsset,
+                    originalPath,
+                    ct);
+
+                // Implicit decision based on path structure
+                if (!rewrittenPath.StartsWith("../"))
+                {
+                    // Include: Add to tracked assets (will be yielded by containing folder)
+                    _includedAssets.Add(resolvedAsset);
+                }
+                // Reference: Asset not added to included list (stays external)
+
+                // Rewrite link in HTML (applies to both Include and Reference)
+                html = html.Replace(originalPath, rewrittenPath);
+            }
+
+            return html;
+        }
+    }
+}

src/Blog/Page/AssetAwareHtmlTemplatedMarkdownPageFolder.cs

@@ -0,0 +1,94 @@
+using System;
+using System.Collections.Generic;
+using System.Runtime.CompilerServices;
+using System.Threading;
+using OwlCore.Storage;
+using WindowsAppCommunity.Blog.Assets;
+
+namespace WindowsAppCommunity.Blog.Page
+{
+    /// <summary>
+    /// Asset-aware virtual folder - extends base with markdown-referenced asset inclusion.
+    /// Creates asset-aware file variant and yields included assets in virtual structure.
+    /// Implements lazy generation - no file system operations during construction.
+    /// </summary>
+    public class AssetAwareHtmlTemplatedMarkdownPageFolder : HtmlTemplatedMarkdownPageFolder
+    {
+        /// <summary>
+        /// Creates asset-aware virtual folder representing single-page output structure with asset management.
+        /// No file system operations occur during construction (lazy generation).
+        /// </summary>
+        /// <param name="markdownSource">Source markdown file to transform</param>
+        /// <param name="templateSource">Template as IFile or IFolder</param>
+        /// <param name="templateFileName">Template file name when source is IFolder (defaults to "template.html")</param>
+        public AssetAwareHtmlTemplatedMarkdownPageFolder(
+            IFile markdownSource, 
+            IStorable templateSource, 
+            string? templateFileName = null)
+            : base(markdownSource, templateSource, templateFileName)
+        {
+        }
+
+        /// <summary>
+        /// Asset link detector for finding relative links in markdown.
+        /// </summary>
+        public required IAssetLinkDetector LinkDetector { get; init; }
+
+        /// <summary>
+        /// Asset resolver for converting paths to IFile instances.
+        /// </summary>
+        public required IAssetResolver Resolver { get; init; }
+
+        /// <summary>
+        /// Inclusion strategy for deciding include vs reference per asset.
+        /// </summary>
+        public required IAssetInclusionStrategy InclusionStrategy { get; init; }
+
+        /// <inheritdoc />
+        public override async IAsyncEnumerable<IStorableChild> GetItemsAsync(
+            StorableType type = StorableType.All,
+            [EnumeratorCancellation] CancellationToken cancellationToken = default)
+        {
+            AssetAwareHtmlTemplatedMarkdownFile? assetAwareFile = null;
+
+            // Yield base items (HTML file + template assets), capturing asset-aware file reference
+            await foreach (var item in base.GetItemsAsync(type, cancellationToken))
+            {
+                // Intercept HTML file creation to replace with asset-aware variant
+                if (item is HtmlTemplatedMarkdownFile htmlFile && assetAwareFile == null)
+                {
+                    // Create asset-aware variant with required properties set
+                    assetAwareFile = new AssetAwareHtmlTemplatedMarkdownFile(
+                        htmlFile.Id,
+                        MarkdownSource,
+                        TemplateSource,
+                        TemplateFileName,
+                        this)
+                    {
+                        Name = htmlFile.Name,
+                        Created = htmlFile.Created,
+                        Modified = htmlFile.Modified,
+                        LinkDetector = LinkDetector,
+                        Resolver = Resolver,
+                        InclusionStrategy = InclusionStrategy
+                    };
+
+                    yield return assetAwareFile;
+                    continue;
+                }
+
+                // Pass through other items (template assets)
+                yield return item;
+            }
+
+            // Yield markdown-referenced assets that were decided for inclusion
+            if (assetAwareFile != null && (type == StorableType.All || type == StorableType.File))
+            {
+                foreach (var includedAsset in assetAwareFile.IncludedAssets)
+                {
+                    yield return (IStorableChild)includedAsset;
+                }
+            }
+        }
+    }
+}