V3.0.0

.gitignore

@@ -369,5 +369,11 @@ FodyWeavers.xsd
 *.pfx
 *.snk
 
+# AI Agents
+.agents/
+.codex/
+.claude/
+.junie/
+
 # Documentation Site
 .site/

kampose.json

@@ -32,13 +32,19 @@
         "projectLogoLightUri": "logo-dark.png",
         "projectLogoDarkUri": "logo-light.png",
         "faviconUri": "ICON.png",
-        "pageFooter": "Copyright © {{now 'yyyy'}} [Kampute](https://kampute.com)",
-        "pageFooterRight": "Built with [Kampose](https://kampute.github.io/kampose/)",
         "groupTypesByNamespace": true,
         "showTypeMembersSummary": true,
         "seeAlsoSubtopics": true,
         "menuItems": [
-          "*"
+            "*"
+        ],
+        "pageFooter": [
+            "- Copyright © {{now 'yyyy'}} Kampute",
+            "- [MIT License](~/LICENSE)",
+            "- [Source code](https://github.com/kampute/doc-toolkit)"
+        ],
+        "pageFooterRight": [
+            "Built with [Kampose](https://kampute.github.io/kampose/)"
         ]
     }
 }

src/Collections/TopicCollection.cs

@@ -313,7 +313,7 @@ public bool TryFindBySubpath(string filePath, [NotNullWhen(true)] out TopicModel
 
             foreach (var (sourceFilePath, fileBasedTopic) in topicsByPath)
             {
-                if (PathHelper.IsSubpath(sourceFilePath, subPath))
+                if (PathHelper.IsSubpath(subPath, sourceFilePath))
                 {
                     if (topic is not null)
                     {

src/DocumentationContext.cs

@@ -1,4 +1,4 @@
-// Copyright (C) Kampute
+// Copyright (C) Kampute
 //
 // Released under the terms of the MIT license.
 // See the LICENSE file in the project root for the full license text.
@@ -127,10 +127,10 @@ public DocumentationContext
         public IDocumentAddressProvider AddressProvider { get; }
 
         /// <summary>
-        /// Gets the object responsible for transforming non-API site-root-relative URLs to an absolute or document-relative URL.
+        /// Gets the object responsible for transforming non-API documentation-root-relative URLs to absolute or document-relative URLs.
         /// </summary>
         /// <value>
-        /// The object responsible for transforming non-API site-root-relative URLs to an absolute or document-relative URL.
+        /// The object responsible for transforming non-API documentation-root-relative URLs to absolute or document-relative URLs.
         /// </value>
         public IUrlTransformer UrlTransformer { get; }
 
@@ -222,13 +222,13 @@ protected void Dispose(bool disposing)
         /// <returns>The URL transformer to use for transforming non-API URLs in the documentation.</returns>
         /// <remarks>
         /// This method creates an implementation of <see cref="IUrlTransformer"/> for transforming non-API
-        /// site-root-relative URLs to absolute or document-relative URLs.
+        /// documentation-root-relative URLs to absolute or document-relative URLs.
         /// <para>
-        /// The default implementation returns an instance of the <see cref="ContextAwareUrlTransformer"/> class.
+        /// The default implementation returns an instance of the <see cref="DocumentationUrlTransformer"/> class.
         /// Override this method in derived classes to provide a custom URL transformer implementation if needed.
         /// </para>
         /// </remarks>
-        protected virtual IUrlTransformer CreateUrlTransformer() => new ContextAwareUrlTransformer(this);
+        protected virtual IUrlTransformer CreateUrlTransformer() => new DocumentationUrlTransformer(this);
 
         /// <summary>
         /// Retrieves all unique namespaces with exported types from the assemblies in the documentation context.

src/IDocumentationContext.cs

@@ -106,11 +106,11 @@ public interface IDocumentationContext : IDisposable
         IDocumentAddressProvider AddressProvider { get; }
 
         /// <summary>
-        /// Gets the object responsible for transforming non-API site-root-relative URLs to an absolute or document-relative URL.
+        /// Gets the object responsible for transforming non-API documentation-root-relative URLs to absolute or document-relative URLs.
         /// </summary>
         /// <value>
-        /// The object responsible for transforming non-API site-root-relative URLs to an absolute or document-relative URL.
+        /// The object responsible for transforming non-API documentation-root-relative URLs to absolute or document-relative URLs.
         /// </value>
         IUrlTransformer UrlTransformer { get; }
     }
-}
+}

src/Kampute.DocToolkit.csproj

@@ -4,7 +4,7 @@
     <TargetFramework>netstandard2.1</TargetFramework>
     <Title>Kampute.DocToolkit</Title>
     <Description>Provides extensible pipeline for generating .NET API documentation by transforming assembly metadata and XML documentation into structured models, with automatic cross-reference resolution, support for multiple output formats (HTML, Markdown), and integration of conceptual topics.</Description>
-    <Version>2.3.0</Version>
+    <Version>3.0.0</Version>
     <Company>Kampute</Company>
     <Authors>Kambiz Khojasteh</Authors>
     <Copyright>Copyright (C) Kampute</Copyright>

src/Routing/RelativeToAbsoluteUrlNormalizer.cs → src/Routing/AbsoluteUrlContextManager.cs

@@ -6,28 +6,27 @@
 namespace Kampute.DocToolkit.Routing
 {
     using System;
-    using System.Diagnostics.CodeAnalysis;
     using System.Runtime.CompilerServices;
 
     /// <summary>
-    /// Converts relative URLs to absolute URLs using a fixed base URL.
+    /// Converts documentation-root-relative URLs to absolute URLs using a fixed documentation root URL.
     /// </summary>
     /// <remarks>
-    /// This class provides a simple implementation of the URL adjustment infrastructure that converts all relative URLs to
-    /// absolute URLs by combining them with a configurable base URL.
+    /// This class provides a simple implementation of the URL adjustment infrastructure that converts documentation-root-relative
+    /// URLs to absolute URLs by combining them with a configurable documentation root URL.
     /// </remarks>
     /// <threadsafety static="true" instance="true"/>
-    public sealed class RelativeToAbsoluteUrlNormalizer : DocumentUrlContextManager
+    public sealed class AbsoluteUrlContextManager : DocumentUrlContextManager
     {
         private readonly string baseUrlString;
 
         /// <summary>
-        /// Initializes a new instance of the <see cref="RelativeToAbsoluteUrlNormalizer"/> class with the specified base URL.
+        /// Initializes a new instance of the <see cref="AbsoluteUrlContextManager"/> class with the specified base URL.
         /// </summary>
         /// <param name="baseUrl">The base URL to use for creating absolute URLs from relative URLs.</param>
         /// <exception cref="ArgumentNullException">Thrown when <paramref name="baseUrl"/> is <see langword="null"/>.</exception>
         /// <exception cref="ArgumentException">Thrown when <paramref name="baseUrl"/> is not an absolute URL.</exception>
-        public RelativeToAbsoluteUrlNormalizer(Uri baseUrl)
+        public AbsoluteUrlContextManager(Uri baseUrl)
             : base()
         {
             if (baseUrl is null)
@@ -40,12 +39,12 @@ public RelativeToAbsoluteUrlNormalizer(Uri baseUrl)
         }
 
         /// <summary>
-        /// Initializes a new instance of the <see cref="RelativeToAbsoluteUrlNormalizer"/> class with the specified base URL string.
+        /// Initializes a new instance of the <see cref="AbsoluteUrlContextManager"/> class with the specified base URL string.
         /// </summary>
         /// <param name="baseUrlString">The base URL to use for creating absolute URLs from relative URLs.</param>
         /// <exception cref="ArgumentNullException">Thrown when <paramref name="baseUrlString"/> is <see langword="null"/>.</exception>
         /// <exception cref="ArgumentException">Thrown when <paramref name="baseUrlString"/> is not an absolute URL.</exception>
-        public RelativeToAbsoluteUrlNormalizer(string baseUrlString)
+        public AbsoluteUrlContextManager(string baseUrlString)
             : base()
         {
             if (baseUrlString is null)
@@ -77,50 +76,53 @@ public RelativeToAbsoluteUrlNormalizer(string baseUrlString)
         protected override UrlContext CreateScope(string directory, IDocumentModel? model) => new AbsoluteUrlContext(this, directory, model);
 
         /// <summary>
-        /// Represents a disposable URL context that converts relative URLs to absolute URLs.
+        /// Represents a disposable URL context that converts documentation-root-relative URLs to absolute URLs.
         /// </summary>
         private sealed class AbsoluteUrlContext : UrlContext
         {
-            private readonly string rootUrlString;
+            private readonly string documentationRootUrlString;
 
             /// <summary>
             /// Initializes a new instance of the <see cref="AbsoluteUrlContext"/> class.
             /// </summary>
-            /// <param name="owner">The owning normalizer instance.</param>
+            /// <param name="owner">The owning context manager.</param>
             /// <param name="directory">The directory path of the document being rendered relative to the documentation root.</param>
             /// <param name="model">The document model associated with the current context or <see langword="null"/> if not applicable.</param>
-            public AbsoluteUrlContext(RelativeToAbsoluteUrlNormalizer owner, string directory, IDocumentModel? model)
+            public AbsoluteUrlContext(AbsoluteUrlContextManager owner, string directory, IDocumentModel? model)
                 : base(owner, directory, model)
             {
-                RootUrl = owner.BaseUrl;
-                rootUrlString = owner.baseUrlString;
+                DocumentationRootUrl = owner.BaseUrl;
+                documentationRootUrlString = owner.baseUrlString;
             }
 
             /// <summary>
             /// Gets the absolute URL to the root of the documentation site for the current document.
             /// </summary>
             /// <value>
-            /// The URL that serves as the reference point for resolving relative URLs within the current document.
+            /// The configured absolute URL of the documentation root, including any path below the web site's root.
             /// </value>
-            public override Uri RootUrl { get; }
+            public override Uri DocumentationRootUrl { get; }
 
             /// <summary>
-            /// Attempts to transform a site-relative URL string into an absolute URL.
+            /// Resolves a documentation-root-relative URL into an absolute URL.
             /// </summary>
-            /// <param name="siteRelativeUrl">The URL string relative to site root to transform.</param>
-            /// <param name="transformedUrl">When this method returns, contains the transformed URL if the transformation succeeded; otherwise, <see langword="null"/>.</param>
-            /// <returns><see langword="true"/> if the URL was successfully transformed; otherwise, <see langword="false"/>.</returns>
-            public override bool TryTransformSiteRelativeUrl(string siteRelativeUrl, [NotNullWhen(true)] out string? transformedUrl)
+            /// <param name="urlString">
+            /// A URL string relative to the documentation root (without the <c>~/</c> marker). The URL consists of a normalized path
+            /// component and may optionally include a query string and/or fragment.
+            /// </param>
+            /// <returns>An absolute URL string combining the base URL with the provided URL.</returns>
+            /// <remarks>
+            /// The method combines the configured documentation root URL with the provided URL string. Query strings and fragments
+            /// are preserved in the result.
+            /// </remarks>
+            /// <exception cref="ArgumentNullException">Thrown when <paramref name="urlString"/> is <see langword="null"/>.</exception>
+            public override string ResolveFromDocumentationRoot(string urlString)
             {
-                if (!IsSiteRelativeUrl(siteRelativeUrl))
-                {
-                    transformedUrl = null;
-                    return false;
-                }
+                if (urlString is null)
+                    throw new ArgumentNullException(nameof(urlString));
 
-                transformedUrl = rootUrlString + siteRelativeUrl;
-                return true;
+                return documentationRootUrlString + urlString;
             }
         }
     }
-}
+}