From 7a5dfd147863ba2a15d593e7406b55e6721246f0 Mon Sep 17 00:00:00 2001
From: Shewart <shewartshepherd23@gmail.com>
Date: Fri, 2 Oct 2026 22:23:27 +0200
Subject: [PATCH 1/5] feat(markdown): generic components in previews, inline
 tags and ComponentPreview
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

RegisterComponentsFromAssembly skipped generic definitions, so <BarChart TItem="…">, data tables and typed selects couldn't be used from markdown. Generic components now register under their bare name and SlotRenderer.Component closes them per use from attributes named after the type parameters, as Razor does. Type arguments accept C# spellings (aliases, T?, T[], List<T>, simple or full names). Without one, object is used when the constraints allow it, with a warning; otherwise an inline .shelldocs-render-error replaces the component instead of breaking the page. A non-generic component with the same name keeps the tag, and AutoTypeTable lists type parameters.
---
 .../Content/AutoTypeTable.razor               |  16 +-
 .../Content/ComponentPreview.razor            |  18 +-
 .../Content/GenericComponents.cs              | 165 ++++++++++++++++++
 .../Content/MarkdownContent.razor             |   5 +-
 .../Content/PreviewFrame.razor                |   9 +-
 .../Content/SlotRenderer.cs                   |  37 +++-
 src/ShellDocs.Components/ShellDocsOptions.cs  |  12 +-
 .../wwwroot/shelldocs-theme.css               |  12 ++
 src/ShellDocs.Markdown/TypeRegistry.cs        |  10 +-
 tests/ShellDocs.Tests/AssemblyScanTests.cs    |   7 +-
 .../ShellDocs.Tests/GenericComponentTests.cs  | 146 ++++++++++++++++
 11 files changed, 409 insertions(+), 28 deletions(-)
 create mode 100644 src/ShellDocs.Components/Content/GenericComponents.cs
 create mode 100644 tests/ShellDocs.Tests/GenericComponentTests.cs

diff --git a/src/ShellDocs.Components/Content/AutoTypeTable.razor b/src/ShellDocs.Components/Content/AutoTypeTable.razor
index 0f635ea..b3ef9e0 100644
--- a/src/ShellDocs.Components/Content/AutoTypeTable.razor
+++ b/src/ShellDocs.Components/Content/AutoTypeTable.razor
@@ -73,8 +73,19 @@ else
     private static List<TypeRowInfo> BuildRows(Type target)
     {
         var rows = new List<TypeRowInfo>();
+
+        // Generic components list their type parameters first, set as TItem="…".
+        // Defaults are read from an instance closed over object, when that's allowed.
+        var instanceType = target;
+        if (target.IsGenericTypeDefinition)
+        {
+            foreach (var tp in target.GetGenericArguments())
+                rows.Add(new TypeRowInfo(tp.Name, "type parameter", null, "Generic type argument, set as an attribute.", true));
+            try { instanceType = target.MakeGenericType(target.GetGenericArguments().Select(_ => typeof(object)).ToArray()); }
+            catch (ArgumentException) { instanceType = null; }
+        }
         object? instance = null;
-        try { instance = Activator.CreateInstance(target); } catch { }
+        try { if (instanceType is not null) instance = Activator.CreateInstance(instanceType); } catch { }
 
         foreach (var prop in target.GetProperties(BindingFlags.Public | BindingFlags.Instance))
         {
@@ -83,7 +94,7 @@ else
             var name = prop.Name;
             var type = FormatType(prop.PropertyType);
             var required = prop.GetCustomAttribute<EditorRequiredAttribute>() is not null;
-            var def = ReadDefault(prop, instance);
+            var def = ReadDefault(instanceType?.GetProperty(name, BindingFlags.Public | BindingFlags.Instance) ?? prop, instance);
             var desc = XmlDocIndex.SummaryFor(prop);
             rows.Add(new TypeRowInfo(name, type, def, desc, required));
         }
@@ -95,6 +106,7 @@ else
     {
         var underlying = Nullable.GetUnderlyingType(t);
         if (underlying is not null) return FormatType(underlying) + "?";
+        if (t.IsGenericParameter) return t.Name;
         if (t == typeof(string)) return "string";
         if (t == typeof(bool)) return "bool";
         if (t == typeof(int)) return "int";
diff --git a/src/ShellDocs.Components/Content/ComponentPreview.razor b/src/ShellDocs.Components/Content/ComponentPreview.razor
index cb17061..d41e5c3 100644
--- a/src/ShellDocs.Components/Content/ComponentPreview.razor
+++ b/src/ShellDocs.Components/Content/ComponentPreview.razor
@@ -8,7 +8,7 @@
 
 <PreviewFrame Content="@(_target is null ? null : RenderTarget)"
               Code="@_source"
-              Error="@(_target is null ? $"Unknown component <{Component}>." : null)"
+              Error="@_error"
               ErrorTitle="ComponentPreview error"
               Id="@_id"
               Name="@Component"
@@ -28,10 +28,25 @@
     private IDictionary<string, object>? _targetParams;
     private string? _source;
     private string? _id;
+    private string? _error;
+    private HashSet<string> _typeParams = new(StringComparer.OrdinalIgnoreCase);
 
     protected override void OnParametersSet()
     {
         _target = Component is null ? null : Registry.Resolve(Component);
+        _error = _target is null ? $"Unknown component <{Component}>." : null;
+        _typeParams = new(StringComparer.OrdinalIgnoreCase);
+        if (_target is { IsGenericTypeDefinition: true } open)
+        {
+            // TItem="Product" closes a generic target, as in Razor.
+            var attrs = (ExtraProps ?? new Dictionary<string, object>())
+                .Where(kv => kv.Value is string)
+                .ToDictionary(kv => kv.Key, kv => (string)kv.Value);
+            _target = GenericComponents.Close(open, attrs, out _, out var error, out var notes);
+            foreach (var note in notes) Logger.LogWarning("ShellDocs: {Note}", note);
+            if (_target is null) _error = error;
+            _typeParams = new(open.GetGenericArguments().Select(p => p.Name), StringComparer.OrdinalIgnoreCase);
+        }
         _targetParams = _target is null ? null : BuildTargetParams(_target);
         _source = BuildSource();
         // Same component twice on a page gets distinct ids via the source hash.
@@ -54,6 +69,7 @@
         {
             foreach (var (k, v) in ExtraProps)
             {
+                if (_typeParams.Contains(k)) continue;
                 if (!props.TryGetValue(k, out var prop))
                 {
                     if (!k.StartsWith('@') && SlotRenderer.HasCatchAll(target)) dict[k] = v;
diff --git a/src/ShellDocs.Components/Content/GenericComponents.cs b/src/ShellDocs.Components/Content/GenericComponents.cs
new file mode 100644
index 0000000..a532cb7
--- /dev/null
+++ b/src/ShellDocs.Components/Content/GenericComponents.cs
@@ -0,0 +1,165 @@
+using System.Collections.Concurrent;
+using System.Reflection;
+using ShellDocs.Markdown;
+
+namespace ShellDocs.Components.Content;
+
+/* Generic components register under their bare name (<BarChart>) as open
+   definitions and are closed per use from attributes named after their type
+   parameters, as Razor writes them: <BarChart TItem="SalesRow" />. A missing
+   type argument falls back to object when the constraints allow it. */
+internal static class GenericComponents
+{
+    private static readonly Dictionary<string, Type> Aliases = new(StringComparer.Ordinal)
+    {
+        ["bool"] = typeof(bool), ["byte"] = typeof(byte), ["sbyte"] = typeof(sbyte), ["char"] = typeof(char),
+        ["decimal"] = typeof(decimal), ["double"] = typeof(double), ["float"] = typeof(float),
+        ["int"] = typeof(int), ["uint"] = typeof(uint), ["long"] = typeof(long), ["ulong"] = typeof(ulong),
+        ["short"] = typeof(short), ["ushort"] = typeof(ushort), ["nint"] = typeof(nint), ["nuint"] = typeof(nuint),
+        ["object"] = typeof(object), ["string"] = typeof(string),
+    };
+
+    // Closes `type` if it's a generic definition. `remaining` is `attrs` without the
+    // type-parameter attributes; `error` is set (and the result null) when it can't close.
+    public static Type? Close(
+        Type type,
+        IReadOnlyDictionary<string, string> attrs,
+        out IReadOnlyDictionary<string, string> remaining,
+        out string? error,
+        out IReadOnlyList<string> notes)
+    {
+        remaining = attrs;
+        error = null;
+        notes = Array.Empty<string>();
+        if (!type.IsGenericTypeDefinition) return type;
+
+        var typeParams = type.GetGenericArguments();
+        var lookup = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
+        foreach (var (k, v) in attrs) lookup[k] = v;
+
+        var args = new Type[typeParams.Length];
+        var messages = new List<string>();
+        for (var i = 0; i < typeParams.Length; i++)
+        {
+            var name = typeParams[i].Name;
+            if (lookup.TryGetValue(name, out var raw))
+            {
+                var resolved = ResolveTypeName(raw, type.Assembly);
+                if (resolved is null)
+                {
+                    error = $"<{TagName(type)}>: can't resolve {name}=\"{raw}\". Use a type name the app references (e.g. \"int\", \"string\", \"MyApp.Models.Product\").";
+                    return null;
+                }
+                args[i] = resolved;
+            }
+            else
+            {
+                args[i] = typeof(object);
+                messages.Add($"<{TagName(type)}>: no {name}=\"…\" attribute; using object.");
+            }
+        }
+
+        Type closed;
+        try { closed = type.MakeGenericType(args); }
+        catch (ArgumentException)
+        {
+            var names = string.Join(", ", typeParams.Select(p => p.Name + "=\"…\""));
+            error = $"<{TagName(type)}> is generic and its type arguments don't satisfy its constraints. Set {names}.";
+            return null;
+        }
+
+        var typeParamNames = new HashSet<string>(typeParams.Select(p => p.Name), StringComparer.OrdinalIgnoreCase);
+        remaining = attrs.Where(kv => !typeParamNames.Contains(kv.Key)).ToDictionary(kv => kv.Key, kv => kv.Value, StringComparer.Ordinal);
+        notes = messages;
+        return closed;
+    }
+
+    public static string TagName(Type type) => TypeRegistry.TagNameOf(type);
+
+    // C# spellings: aliases, `T?`, `T[]`, `List<T>`, simple or full type names.
+    // Searches the component's assembly first, then every loaded assembly.
+    internal static Type? ResolveTypeName(string raw, Assembly? preferred = null)
+    {
+        var name = raw.Trim();
+        if (name.StartsWith('@')) name = name[1..].Trim();
+        if (name.Length == 0) return null;
+
+        if (name.EndsWith('?'))
+        {
+            var inner = ResolveTypeName(name[..^1], preferred);
+            if (inner is null) return null;
+            return inner.IsValueType ? typeof(Nullable<>).MakeGenericType(inner) : inner;
+        }
+        if (name.EndsWith("[]", StringComparison.Ordinal))
+            return ResolveTypeName(name[..^2], preferred)?.MakeArrayType();
+
+        var lt = name.IndexOf('<');
+        if (lt > 0 && name.EndsWith('>'))
+        {
+            var argNames = SplitTopLevel(name[(lt + 1)..^1]);
+            var def = FindType($"{name[..lt].Trim()}`{argNames.Count}", preferred);
+            if (def is null) return null;
+            var typeArgs = new Type[argNames.Count];
+            for (var i = 0; i < argNames.Count; i++)
+            {
+                var a = ResolveTypeName(argNames[i], preferred);
+                if (a is null) return null;
+                typeArgs[i] = a;
+            }
+            try { return def.MakeGenericType(typeArgs); }
+            catch (ArgumentException) { return null; }
+        }
+
+        if (Aliases.TryGetValue(name, out var alias)) return alias;
+        return FindType(name, preferred);
+    }
+
+    private static readonly ConcurrentDictionary<(string, Assembly?), Type?> _found = new();
+
+    private static Type? FindType(string name, Assembly? preferred)
+        => _found.GetOrAdd((name, preferred), key => Search(key.Item1, key.Item2));
+
+    private static Type? Search(string name, Assembly? preferred)
+    {
+        var direct = Type.GetType(name, throwOnError: false) ?? Type.GetType("System." + name, throwOnError: false);
+        if (direct is not null) return direct;
+
+        var assemblies = AppDomain.CurrentDomain.GetAssemblies().Where(a => !a.IsDynamic);
+        if (preferred is not null) assemblies = assemblies.OrderBy(a => a == preferred ? 0 : 1);
+
+        Type? bySimpleName = null;
+        foreach (var assembly in assemblies)
+        {
+            var full = assembly.GetType(name, throwOnError: false);
+            if (full is not null) return full;
+            if (bySimpleName is not null || name.Contains('.')) continue;
+            bySimpleName = ExportedTypes(assembly).FirstOrDefault(t => t.Name == name);
+        }
+        return bySimpleName;
+    }
+
+    private static IEnumerable<Type> ExportedTypes(Assembly assembly)
+    {
+        try { return assembly.GetExportedTypes(); }
+        catch { return Array.Empty<Type>(); }
+    }
+
+    private static List<string> SplitTopLevel(string s)
+    {
+        var parts = new List<string>();
+        var depth = 0;
+        var start = 0;
+        for (var i = 0; i < s.Length; i++)
+        {
+            if (s[i] == '<') depth++;
+            else if (s[i] == '>') depth--;
+            else if (s[i] == ',' && depth == 0)
+            {
+                parts.Add(s[start..i].Trim());
+                start = i + 1;
+            }
+        }
+        parts.Add(s[start..].Trim());
+        return parts;
+    }
+}
diff --git a/src/ShellDocs.Components/Content/MarkdownContent.razor b/src/ShellDocs.Components/Content/MarkdownContent.razor
index 12bf0ad..9330a72 100644
--- a/src/ShellDocs.Components/Content/MarkdownContent.razor
+++ b/src/ShellDocs.Components/Content/MarkdownContent.razor
@@ -23,7 +23,7 @@
             {
                 @if (slot.Slot is ComponentSlot comp)
                 {
-                    <DynamicComponent Type="comp.ComponentType" Parameters="BuildParameters(comp)" />
+                    @SlotRenderer.Component(Renderer, comp.ComponentType, comp.Parameters, comp.ChildContentRaw, Logger)
                 }
                 else if (slot.Slot is PreviewSlot preview)
                 {
@@ -52,7 +52,4 @@
         if (_parts is null) return;
         try { await JS.InvokeVoidAsync("shelldocsHighlight"); } catch { }
     }
-
-    private IDictionary<string, object> BuildParameters(ComponentSlot slot) =>
-        SlotRenderer.BuildParameters(Renderer, slot.ComponentType, slot.Parameters, slot.ChildContentRaw, Logger);
 }
diff --git a/src/ShellDocs.Components/Content/PreviewFrame.razor b/src/ShellDocs.Components/Content/PreviewFrame.razor
index 5bf4f12..c7df446 100644
--- a/src/ShellDocs.Components/Content/PreviewFrame.razor
+++ b/src/ShellDocs.Components/Content/PreviewFrame.razor
@@ -81,8 +81,7 @@
         }
         else
         {
-            <DynamicComponent Type="Preview!.ComponentType"
-                              Parameters="BuildParameters(Preview!.Parameters, Preview!.ChildContentRaw)" />
+            @SlotRenderer.Component(Renderer, Preview!.ComponentType!, Preview!.Parameters, Preview!.ChildContentRaw, Logger, razorChildren: true)
         }
     </div>
     <div class="preview-panel preview-code-panel" role="tabpanel" id="@PartId("panel-code")" aria-labelledby="@PartId("tab-code")" data-preview-panel="code">
@@ -132,13 +131,9 @@
             _bugHref = _suggestHref = null;
             return;
         }
-        var name = Name ?? Preview?.ComponentType?.Name ?? Title ?? "docs";
+        var name = Name ?? (Preview?.ComponentType is { } t ? GenericComponents.TagName(t) : null) ?? Title ?? "docs";
         var pageUrl = PreviewLinks.PageUrl(Options, path, Id);
         _bugHref = PreviewLinks.BugReport(tracker, name, pageUrl);
         _suggestHref = PreviewLinks.Suggestion(tracker, name, pageUrl);
     }
-
-    // Only reached when ErrorMessage is null, i.e. ComponentType is non-null.
-    private IDictionary<string, object> BuildParameters(IReadOnlyDictionary<string, string> attrs, string? childContentRaw) =>
-        SlotRenderer.BuildParameters(Renderer, Preview!.ComponentType!, attrs, childContentRaw, Logger, razorChildren: true);
 }
diff --git a/src/ShellDocs.Components/Content/SlotRenderer.cs b/src/ShellDocs.Components/Content/SlotRenderer.cs
index 9ce258b..96a3a69 100644
--- a/src/ShellDocs.Components/Content/SlotRenderer.cs
+++ b/src/ShellDocs.Components/Content/SlotRenderer.cs
@@ -42,12 +42,36 @@ public static RenderFragment FromRazor(MarkdownRenderer renderer, string raw, IL
     }
 
     private static void Emit(RenderTreeBuilder builder, ref int seq, MarkdownRenderer renderer, ComponentSlot slot, ILogger? logger)
+        => builder.AddContent(seq++, Component(renderer, slot.ComponentType, slot.Parameters, slot.ChildContentRaw, logger));
+
+    /* One registered component from markdown. Generic definitions are closed from
+       their type-parameter attributes first; one that can't be closed renders a
+       visible error instead of throwing. */
+    public static RenderFragment Component(
+        MarkdownRenderer renderer,
+        Type type,
+        IReadOnlyDictionary<string, string> attrs,
+        string? childContentRaw,
+        ILogger? logger = null,
+        bool razorChildren = false) => builder =>
     {
-        builder.OpenComponent<DynamicComponent>(seq++);
-        builder.AddAttribute(seq++, "Type", slot.ComponentType);
-        builder.AddAttribute(seq++, "Parameters", BuildParameters(renderer, slot.ComponentType, slot.Parameters, slot.ChildContentRaw, logger));
+        var closed = GenericComponents.Close(type, attrs, out var remaining, out var error, out var notes);
+        foreach (var note in notes) logger?.LogWarning("ShellDocs: {Note}", note);
+        if (closed is null)
+        {
+            logger?.LogWarning("ShellDocs: {Error}", error);
+            builder.OpenElement(0, "div");
+            builder.AddAttribute(1, "class", "shelldocs-render-error");
+            builder.AddAttribute(2, "role", "alert");
+            builder.AddContent(3, error);
+            builder.CloseElement();
+            return;
+        }
+        builder.OpenComponent<DynamicComponent>(4);
+        builder.AddAttribute(5, "Type", closed);
+        builder.AddAttribute(6, "Parameters", BuildParameters(renderer, closed, remaining, childContentRaw, logger, razorChildren));
         builder.CloseComponent();
-    }
+    };
 
     /* Elements are real render-tree elements, not markup strings, so wrappers keep
        their component children under interactive re-renders. One region per node
@@ -67,10 +91,7 @@ private static void EmitNodes(RenderTreeBuilder builder, MarkdownRenderer render
                     break;
 
                 case PreviewComponentNode comp:
-                    builder.OpenComponent<DynamicComponent>(0);
-                    builder.AddAttribute(1, "Type", comp.ComponentType);
-                    builder.AddAttribute(2, "Parameters", BuildParameters(renderer, comp.ComponentType, comp.Parameters, comp.ChildContentRaw, logger, razorChildren: true));
-                    builder.CloseComponent();
+                    builder.AddContent(0, Component(renderer, comp.ComponentType, comp.Parameters, comp.ChildContentRaw, logger, razorChildren: true));
                     break;
 
                 case PreviewElementNode el:
diff --git a/src/ShellDocs.Components/ShellDocsOptions.cs b/src/ShellDocs.Components/ShellDocsOptions.cs
index 75d5fbd..d8d3a2d 100644
--- a/src/ShellDocs.Components/ShellDocsOptions.cs
+++ b/src/ShellDocs.Components/ShellDocsOptions.cs
@@ -76,7 +76,8 @@ public ShellDocsOptions RegisterComponent(Type type, string tagName)
         return this;
     }
 
-    // Registers every public, concrete, non-generic component in the assembly, skipping [ShellDocsIgnore].
+    // Registers every public, concrete component in the assembly, skipping [ShellDocsIgnore].
+    // Generic components register under their bare name and are closed per use (TItem="…").
     public ShellDocsOptions RegisterComponentsFromAssembly<TMarker>(Func<Type, bool>? filter = null)
         => RegisterComponentsFromAssembly(typeof(TMarker).Assembly, filter);
 
@@ -123,7 +124,6 @@ private static IEnumerable<Type> DiscoverComponentTypes(Assembly assembly)
             if (t is null) continue;
             if (!t.IsClass || t.IsAbstract) continue;
             if (!t.IsPublic && !t.IsNestedPublic) continue;
-            if (t.IsGenericTypeDefinition) continue;
             if (!typeof(ComponentBase).IsAssignableFrom(t)) continue;
             if (t.IsDefined(typeof(ShellDocsIgnoreAttribute), inherit: false)) continue;
             yield return t;
@@ -196,8 +196,16 @@ internal TypeRegistry BuildTypeRegistry()
             registry.Register(type);
             registry.Register(BuiltInAliasPrefix + type.Name, type);
         }
+        // A library shipping both Select and Select<T> keeps <Select> for the non-generic one.
+        var nonGenericTags = RegisteredComponents
+            .Where(t => !t.IsGenericTypeDefinition && !ComponentAliases.ContainsKey(t))
+            .Select(TypeRegistry.TagNameOf)
+            .ToHashSet(StringComparer.Ordinal);
         foreach (var type in RegisteredComponents)
         {
+            if (type.IsGenericTypeDefinition && !ComponentAliases.ContainsKey(type)
+                && nonGenericTags.Contains(TypeRegistry.TagNameOf(type)))
+                continue;
             if (ComponentAliases.TryGetValue(type, out var alias))
                 registry.Register(alias, type);
             else
diff --git a/src/ShellDocs.Components/wwwroot/shelldocs-theme.css b/src/ShellDocs.Components/wwwroot/shelldocs-theme.css
index e0dd013..1d92862 100644
--- a/src/ShellDocs.Components/wwwroot/shelldocs-theme.css
+++ b/src/ShellDocs.Components/wwwroot/shelldocs-theme.css
@@ -162,6 +162,18 @@ body { margin: 0; min-height: 100vh; }
     font-feature-settings: 'ss01', 'cv02';
 }
 
+/* A component in markdown that can't render (e.g. a generic one whose type
+   argument doesn't resolve) shows this instead of breaking the page. */
+.shelldocs-render-error {
+    padding: 0.5rem 0.75rem;
+    border: 1px solid color-mix(in oklch, var(--error, oklch(0.637 0.237 25.331)) 40%, var(--border));
+    border-radius: calc(var(--radius) - 2px);
+    background: color-mix(in oklch, var(--error, oklch(0.637 0.237 25.331)) 10%, transparent);
+    color: var(--foreground);
+    font-family: var(--font-mono);
+    font-size: 0.8125rem;
+}
+
 /* Lock page scroll while the mobile nav is open. On <html>, not the page shell:
    overflow on the shell would make it the sticky header's scroll container, and
    the header would scroll away from above the drawer. */
diff --git a/src/ShellDocs.Markdown/TypeRegistry.cs b/src/ShellDocs.Markdown/TypeRegistry.cs
index 1b405e8..bc9f1ef 100644
--- a/src/ShellDocs.Markdown/TypeRegistry.cs
+++ b/src/ShellDocs.Markdown/TypeRegistry.cs
@@ -7,7 +7,15 @@ public class TypeRegistry
 
     public TypeRegistry Register<T>() where T : class => Register(typeof(T));
 
-    public TypeRegistry Register(Type type) => Register(type.Name, type);
+    public TypeRegistry Register(Type type) => Register(TagNameOf(type), type);
+
+    // A generic component's tag is its bare name: BarChart<TItem> is <BarChart>.
+    public static string TagNameOf(Type type)
+    {
+        var name = type.Name;
+        var tick = name.IndexOf('`');
+        return tick < 0 ? name : name[..tick];
+    }
 
     // Last registration wins; a tag re-pointed at a different type is recorded in Collisions.
     public TypeRegistry Register(string tagName, Type type)
diff --git a/tests/ShellDocs.Tests/AssemblyScanTests.cs b/tests/ShellDocs.Tests/AssemblyScanTests.cs
index 8f8fe0d..5ae483c 100644
--- a/tests/ShellDocs.Tests/AssemblyScanTests.cs
+++ b/tests/ShellDocs.Tests/AssemblyScanTests.cs
@@ -28,12 +28,13 @@ public void RegisterComponentsFromAssembly_SkipsAbstractTypes()
     }
 
     [Fact]
-    public void RegisterComponentsFromAssembly_SkipsGenericDefinitions()
+    public void RegisterComponentsFromAssembly_IncludesGenericDefinitions_UnderTheirBareName()
     {
         var options = new ShellDocsOptions();
         options.RegisterComponentsFromAssembly<TestMarker>();
 
-        Assert.DoesNotContain(options.RegisteredComponents, t => t.Name.StartsWith("GenericShouldSkip"));
+        Assert.Contains(typeof(ScannableGeneric<>), options.RegisteredComponents);
+        Assert.Equal(typeof(ScannableGeneric<>), options.BuildTypeRegistry().Resolve("ScannableGeneric"));
     }
 
     [Fact]
@@ -87,7 +88,7 @@ public class TestMarker { }
     public class ScannableAlpha : ComponentBase { }
     public class ScannableBeta : ComponentBase { }
     public abstract class AbstractShouldSkip : ComponentBase { }
-    public class GenericShouldSkip<T> : ComponentBase { }
+    public class ScannableGeneric<T> : ComponentBase { }
     public class NotAComponent { }
     [ShellDocsIgnore] public class IgnoredExplicitly : ComponentBase { }
 }
diff --git a/tests/ShellDocs.Tests/GenericComponentTests.cs b/tests/ShellDocs.Tests/GenericComponentTests.cs
new file mode 100644
index 0000000..b530992
--- /dev/null
+++ b/tests/ShellDocs.Tests/GenericComponentTests.cs
@@ -0,0 +1,146 @@
+using Microsoft.AspNetCore.Components;
+using Microsoft.AspNetCore.Components.Rendering;
+using ShellDocs.Components;
+using ShellDocs.Components.Content;
+using ShellDocs.Markdown;
+using Xunit;
+
+namespace ShellDocs.Tests;
+
+public class GenericComponentTests
+{
+    public class Widget { }
+
+    // Renders the closed type argument so tests can see what it was closed over.
+    public class Grid<TItem> : ComponentBase
+    {
+        [Parameter] public IEnumerable<TItem>? Items { get; set; }
+        [Parameter] public string? Caption { get; set; }
+
+        protected override void BuildRenderTree(RenderTreeBuilder b)
+        {
+            b.OpenElement(0, "table");
+            b.AddAttribute(1, "data-item", typeof(TItem).Name);
+            b.AddAttribute(2, "data-caption", Caption);
+            b.CloseElement();
+        }
+    }
+
+    public class StructOnly<T> : ComponentBase where T : struct
+    {
+        protected override void BuildRenderTree(RenderTreeBuilder b)
+        {
+            b.OpenElement(0, "span");
+            b.AddAttribute(1, "data-item", typeof(T).Name);
+            b.CloseElement();
+        }
+    }
+
+    public class Picker : ComponentBase { }
+    public class Picker<T> : ComponentBase { }
+
+    private static ComponentRenderHarness Harness() => new(o =>
+    {
+        o.ContentRoot = Path.Combine(Path.GetTempPath(), "shelldocs-no-content-" + Guid.NewGuid().ToString("N"));
+        o.RegisterComponent(typeof(Grid<>));
+        o.RegisterComponent(typeof(StructOnly<>));
+    });
+
+    private static Task<string> Render(ComponentRenderHarness harness, string markdown)
+        => harness.RenderAsync<MarkdownContent>(new() { ["Markdown"] = markdown });
+
+    [Fact]
+    public void Registry_UsesTheBareName_ForGenericDefinitions()
+    {
+        Assert.Equal("Grid", TypeRegistry.TagNameOf(typeof(Grid<>)));
+        Assert.Equal("Grid", TypeRegistry.TagNameOf(typeof(Grid<int>)));
+        Assert.Equal(typeof(Grid<>), new TypeRegistry().Register(typeof(Grid<>)).Resolve("Grid"));
+    }
+
+    [Fact]
+    public void Registry_PrefersTheNonGenericComponent_WhenBothExist()
+    {
+        var options = new ShellDocsOptions();
+        options.RegisterComponent(typeof(Picker<>));
+        options.RegisterComponent(typeof(Picker));
+        var registry = options.BuildTypeRegistry();
+
+        Assert.Equal(typeof(Picker), registry.Resolve("Picker"));
+        Assert.Empty(registry.Collisions);
+    }
+
+    [Fact]
+    public async Task RazorPreview_ClosesGenericFromTypeParameterAttribute()
+    {
+        var html = await Render(Harness(), "```razor:preview\n<Grid TItem=\"int\" Caption=\"Totals\" />\n```");
+
+        Assert.Contains("data-item=\"Int32\"", html);
+        Assert.Contains("data-caption=\"Totals\"", html);
+        Assert.DoesNotContain("shelldocs-render-error", html);
+    }
+
+    [Fact]
+    public async Task InlineTag_InProse_ClosesGenericToo()
+    {
+        var html = await Render(Harness(), "Text.\n\n<Grid TItem=\"ShellDocs.Tests.GenericComponentTests+Widget\" />\n");
+        Assert.Contains("data-item=\"Widget\"", html);
+    }
+
+    [Fact]
+    public async Task MissingTypeArgument_FallsBackToObject_WithAWarning()
+    {
+        var harness = Harness();
+        var html = await Render(harness, "```razor:preview\n<Grid />\n```");
+
+        Assert.Contains("data-item=\"Object\"", html);
+        Assert.Contains(harness.Logs.Messages, m => m.Contains("no TItem=") && m.Contains("using object"));
+    }
+
+    [Fact]
+    public async Task ConstraintOrUnknownType_RendersAVisibleError()
+    {
+        var constrained = await Render(Harness(), "```razor:preview\n<StructOnly />\n```");
+        Assert.Contains("shelldocs-render-error", constrained);
+        Assert.Contains("Set T=", constrained);
+
+        var unknown = await Render(Harness(), "```razor:preview\n<Grid TItem=\"No.Such.Type\" />\n```");
+        Assert.Contains("shelldocs-render-error", unknown);
+        Assert.Contains("can&#x27;t resolve TItem", unknown);
+    }
+
+    [Fact]
+    public async Task ComponentPreview_ClosesGenericTarget()
+    {
+        var html = await Harness().RenderAsync<ComponentPreview>(new()
+        {
+            ["Component"] = "Grid",
+            ["ExtraProps"] = new Dictionary<string, object> { ["TItem"] = "decimal", ["Caption"] = "Prices" }
+        });
+
+        Assert.Contains("data-item=\"Decimal\"", html);
+        Assert.Contains("data-caption=\"Prices\"", html);
+        Assert.Contains("id=\"example-grid-", html);
+    }
+
+    [Theory]
+    [InlineData("int", typeof(int))]
+    [InlineData("int?", typeof(int?))]
+    [InlineData("string[]", typeof(string[]))]
+    [InlineData("List<int>", typeof(List<int>))]
+    [InlineData("Dictionary<string, List<int>>", typeof(Dictionary<string, List<int>>))]
+    [InlineData("DateTime", typeof(DateTime))]
+    [InlineData("System.Guid", typeof(Guid))]
+    [InlineData("@double", typeof(double))]
+    public void ResolveTypeName_HandlesCSharpSpellings(string name, Type expected)
+        => Assert.Equal(expected, GenericComponents.ResolveTypeName(name));
+
+    [Fact]
+    public async Task AutoTypeTable_ListsTypeParameters_ForGenericComponents()
+    {
+        var html = await Harness().RenderAsync<AutoTypeTable>(new() { ["Component"] = "Grid" });
+
+        Assert.Contains("<code>TItem</code>", html);
+        Assert.Contains("type parameter", html);
+        Assert.Contains("IEnumerable&lt;TItem&gt;?", html);
+    }
+}

From 55e1176702c8307d78db4ff8209bbe7c44accd0b Mon Sep 17 00:00:00 2001
From: Shewart <shewartshepherd23@gmail.com>
Date: Fri, 2 Oct 2026 22:23:28 +0200
Subject: [PATCH 2/5] feat(redirects): redirect folders, version roots and
 moved URLs

Folder URLs and version roots go to their first page (/docs prefers unversioned pages, then the latest version), unversioned URLs that exist in the latest version go there, and AddRedirect adds segment-aware prefix rules (301; computed ones are 302). Middleware added through an IStartupFilter answers them before routing, so dotted version roots that {*Path:nonfile} can't match work too, and serves /_shelldocs/redirects.json, which shelldocs build writes out as static redirect pages. EnableRedirects = false opts out. ShellDocs.Components now references the ASP.NET Core shared framework for the middleware; it already read content from disk.
---
 src/ShellDocs.CLI/Commands/PrerenderRunner.cs |  60 ++++++
 .../Content/SlotRenderer.cs                   |   3 +
 .../DocsRedirectMiddleware.cs                 |  50 +++++
 src/ShellDocs.Components/DocsRedirects.cs     | 140 ++++++++++++
 .../ServiceCollectionExtensions.cs            |   4 +
 .../ShellDocs.Components.csproj               |   5 +-
 src/ShellDocs.Components/ShellDocsOptions.cs  |  18 ++
 src/ShellDocs.Core/NavigationGraph.cs         |  16 ++
 tests/ShellDocs.Tests/RedirectTests.cs        | 203 ++++++++++++++++++
 9 files changed, 496 insertions(+), 3 deletions(-)
 create mode 100644 src/ShellDocs.Components/DocsRedirectMiddleware.cs
 create mode 100644 src/ShellDocs.Components/DocsRedirects.cs
 create mode 100644 tests/ShellDocs.Tests/RedirectTests.cs

diff --git a/src/ShellDocs.CLI/Commands/PrerenderRunner.cs b/src/ShellDocs.CLI/Commands/PrerenderRunner.cs
index a96fbaa..fcb1076 100644
--- a/src/ShellDocs.CLI/Commands/PrerenderRunner.cs
+++ b/src/ShellDocs.CLI/Commands/PrerenderRunner.cs
@@ -1,4 +1,6 @@
 using System.Diagnostics;
+using System.Net;
+using System.Text.Json;
 using System.Text.RegularExpressions;
 using Spectre.Console;
 
@@ -110,6 +112,9 @@ void OnStreamLine(string line)
             }
 
             AnsiConsole.MarkupLine($"[dim]prerender:[/] wrote [green]{rendered}[/] page(s)" + (failed > 0 ? $", [yellow]{failed}[/] failed" : ""));
+
+            var redirects = WriteRedirects(http, outputDir);
+            if (redirects > 0) AnsiConsole.MarkupLine($"[dim]redirects:[/] wrote [cyan]{redirects}[/] redirect page(s)");
             return new Result(failed == 0, rendered, failed);
         }
         finally
@@ -118,6 +123,61 @@ void OnStreamLine(string line)
         }
     }
 
+    private record RedirectEntry(string From, string To);
+
+    // The app serves its redirect map (DocsRedirectMiddleware); each source URL without
+    // a prerendered page gets a page that forwards to the target. An app on an older
+    // ShellDocs, or with redirects off, answers 404 and nothing is written.
+    private static int WriteRedirects(HttpClient http, string outputDir)
+    {
+        List<RedirectEntry>? entries;
+        try
+        {
+            var response = http.GetAsync("/_shelldocs/redirects.json").GetAwaiter().GetResult();
+            if (!response.IsSuccessStatusCode) return 0;
+            var json = response.Content.ReadAsStringAsync().GetAwaiter().GetResult();
+            entries = JsonSerializer.Deserialize<List<RedirectEntry>>(json, new JsonSerializerOptions { PropertyNameCaseInsensitive = true });
+        }
+        catch (Exception ex)
+        {
+            AnsiConsole.MarkupLine($"  [yellow]warn:[/] couldn't read the redirect map: {ex.Message}");
+            return 0;
+        }
+
+        var written = 0;
+        foreach (var entry in entries ?? new())
+        {
+            var outPath = UrlToFilePath(entry.From, outputDir);
+            if (File.Exists(outPath)) continue;
+            Directory.CreateDirectory(Path.GetDirectoryName(outPath)!);
+            File.WriteAllText(outPath, RedirectPage(entry.To));
+            written++;
+        }
+        return written;
+    }
+
+    // Target is base-relative so `--base-href` (which rewrites <base>) keeps it right.
+    internal static string RedirectPage(string to)
+    {
+        var relative = to.TrimStart('/');
+        var attr = WebUtility.HtmlEncode(relative);
+        var js = JsonSerializer.Serialize(relative);
+        return $$"""
+            <!DOCTYPE html>
+            <html lang="en">
+            <head>
+            <meta charset="utf-8" />
+            <base href="/" />
+            <title>Redirecting…</title>
+            <meta name="robots" content="noindex" />
+            <meta http-equiv="refresh" content="0; url={{attr}}" />
+            <script>location.replace(new URL({{js}}, document.baseURI).href + location.search + location.hash);</script>
+            </head>
+            <body><a href="{{attr}}">Redirecting…</a></body>
+            </html>
+            """;
+    }
+
     private static string InferAssemblyName(string csproj)
     {
         try
diff --git a/src/ShellDocs.Components/Content/SlotRenderer.cs b/src/ShellDocs.Components/Content/SlotRenderer.cs
index 96a3a69..0073de0 100644
--- a/src/ShellDocs.Components/Content/SlotRenderer.cs
+++ b/src/ShellDocs.Components/Content/SlotRenderer.cs
@@ -9,6 +9,9 @@
 
 namespace ShellDocs.Components.Content;
 
+// Sequence numbers follow the parsed markup, not source order; regions per node keep them stable.
+#pragma warning disable ASP0006
+
 // Renders markdown/HTML containing component tags as real DynamicComponents,
 // recursively, so components nest inside previews and ChildContent.
 internal static class SlotRenderer
diff --git a/src/ShellDocs.Components/DocsRedirectMiddleware.cs b/src/ShellDocs.Components/DocsRedirectMiddleware.cs
new file mode 100644
index 0000000..544e6be
--- /dev/null
+++ b/src/ShellDocs.Components/DocsRedirectMiddleware.cs
@@ -0,0 +1,50 @@
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Hosting;
+using Microsoft.AspNetCore.Http;
+
+namespace ShellDocs.Components;
+
+/* Answers DocsRedirects before routing, so a version root whose last segment has a
+   dot (/docs/v0.2.1, which `{*Path:nonfile}` routes can't match) redirects too.
+   Also serves the full map to `shelldocs build`, which writes it as static pages. */
+internal sealed class DocsRedirectMiddleware
+{
+    public const string MapPath = "/_shelldocs/redirects.json";
+
+    private readonly RequestDelegate _next;
+    private readonly DocsRedirects _redirects;
+
+    public DocsRedirectMiddleware(RequestDelegate next, DocsRedirects redirects)
+    {
+        _next = next;
+        _redirects = redirects;
+    }
+
+    public Task InvokeAsync(HttpContext context)
+    {
+        var request = context.Request;
+        if (!HttpMethods.IsGet(request.Method) && !HttpMethods.IsHead(request.Method))
+            return _next(context);
+
+        var path = request.Path.Value ?? "/";
+        if (string.Equals(path, MapPath, StringComparison.OrdinalIgnoreCase))
+            return context.Response.WriteAsJsonAsync(_redirects.All().Select(r => new { from = r.From, to = r.To }));
+
+        var target = _redirects.Resolve(path);
+        if (target is null) return _next(context);
+
+        context.Response.StatusCode = target.Permanent ? StatusCodes.Status301MovedPermanently : StatusCodes.Status302Found;
+        context.Response.Headers.Location = request.PathBase + target.Url + request.QueryString;
+        return Task.CompletedTask;
+    }
+}
+
+// Puts the middleware first in the pipeline without a Program.cs change.
+internal sealed class DocsRedirectStartupFilter : IStartupFilter
+{
+    public Action<IApplicationBuilder> Configure(Action<IApplicationBuilder> next) => app =>
+    {
+        app.UseMiddleware<DocsRedirectMiddleware>();
+        next(app);
+    };
+}
diff --git a/src/ShellDocs.Components/DocsRedirects.cs b/src/ShellDocs.Components/DocsRedirects.cs
new file mode 100644
index 0000000..79bb04e
--- /dev/null
+++ b/src/ShellDocs.Components/DocsRedirects.cs
@@ -0,0 +1,140 @@
+using ShellDocs.Core;
+
+namespace ShellDocs.Components;
+
+public record DocsRedirectTarget(string Url, bool Permanent);
+
+/* Where a URL that isn't a page should go. Computed from the graph and versions:
+   content folders and version roots → their first page (a folder that holds version
+   folders → its first unversioned page, else the latest version's), and unversioned
+   URLs that exist in the latest version → that page. AddRedirect rules apply on top
+   and may chain into the computed ones. Existing pages are never redirected except
+   by an explicit rule. */
+public sealed class DocsRedirects
+{
+    private const int MaxHops = 8;
+
+    private readonly ShellDocsOptions _options;
+    private readonly NavigationGraph _graph;
+    private readonly DocsVersionResolver _versions;
+    private readonly Lazy<IReadOnlyDictionary<string, string>> _computed;
+
+    public DocsRedirects(ShellDocsOptions options, NavigationGraph graph, DocsVersionResolver versions)
+    {
+        _options = options;
+        _graph = graph;
+        _versions = versions;
+        _computed = new Lazy<IReadOnlyDictionary<string, string>>(Compute);
+    }
+
+    public DocsRedirectTarget? Resolve(string? path)
+    {
+        var start = UrlPath.Normalize(path);
+        var current = start;
+        var permanent = true;
+        for (var hop = 0; hop < MaxHops; hop++)
+        {
+            string? next;
+            if (ApplyRule(current) is { } rule)
+            {
+                next = rule.Url;
+                permanent &= rule.Permanent;
+            }
+            else if (_graph.ResolveByUrl(current) is null && _computed.Value.TryGetValue(current, out var target))
+            {
+                next = target;
+                permanent = false;
+            }
+            else break;
+
+            if (string.Equals(next, current, StringComparison.OrdinalIgnoreCase)) break;
+            current = next;
+        }
+        return string.Equals(current, start, StringComparison.OrdinalIgnoreCase) ? null : new DocsRedirectTarget(current, permanent);
+    }
+
+    // Every redirecting URL that can be listed up front, for static output.
+    public IReadOnlyList<(string From, string To)> All()
+    {
+        var sources = new HashSet<string>(_computed.Value.Keys, StringComparer.OrdinalIgnoreCase);
+        foreach (var rule in _options.Redirects)
+        {
+            sources.Add(UrlPath.Normalize(rule.From));
+            foreach (var page in _graph.Flatten().Where(n => n.Kind == NodeKind.Page && UrlPath.IsUnder(n.Url, rule.To)))
+                sources.Add(UrlPath.Combine(rule.From, UrlPath.RelativeTo(page.Url, rule.To)));
+        }
+        return sources
+            .Select(s => (From: s, Target: Resolve(s)))
+            .Where(x => x.Target is not null)
+            .Select(x => (x.From, x.Target!.Url))
+            .OrderBy(x => x.From, StringComparer.OrdinalIgnoreCase)
+            .ToList();
+    }
+
+    private DocsRedirectTarget? ApplyRule(string path)
+    {
+        foreach (var rule in _options.Redirects)
+        {
+            // Already inside the target: "/docs" → "/docs/v2" must not re-match /docs/v2/x.
+            if (!UrlPath.IsUnder(path, rule.From) || UrlPath.IsUnder(path, rule.To)) continue;
+            return new DocsRedirectTarget(UrlPath.Combine(rule.To, UrlPath.RelativeTo(path, rule.From)), rule.Permanent);
+        }
+        return null;
+    }
+
+    private IReadOnlyDictionary<string, string> Compute()
+    {
+        var map = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
+        void Add(string from, string? to)
+        {
+            from = UrlPath.Normalize(from);
+            if (to is null || from == "/" || map.ContainsKey(from) || _graph.ResolveByUrl(from) is not null) return;
+            to = UrlPath.Normalize(to);
+            if (!string.Equals(from, to, StringComparison.OrdinalIgnoreCase)) map[from] = to;
+        }
+
+        foreach (var version in _versions.Versions)
+            Add(version.RootUrl, _versions.GetVersionHref(null, version));
+
+        var folders = _graph.Folders().ToList();
+        foreach (var (url, _) in folders)
+            Add(url, FolderTarget(url));
+
+        var latest = _versions.Versions.FirstOrDefault(v => v.IsLatest);
+        if (latest is not null)
+        {
+            var parent = Parent(latest.RootUrl);
+            foreach (var page in _graph.Flatten().Where(n => n.Kind == NodeKind.Page && UrlPath.IsUnder(n.Url, latest.RootUrl)))
+                AddLegacy(page.Url, page.Url);
+            foreach (var (url, _) in folders.Where(f => UrlPath.IsUnder(f.Url, latest.RootUrl)))
+                AddLegacy(url, FolderTarget(url));
+
+            void AddLegacy(string versionedUrl, string? target)
+            {
+                var legacy = UrlPath.Combine(parent, UrlPath.RelativeTo(versionedUrl, latest.RootUrl));
+                if (_versions.FindContaining(legacy) is null) Add(legacy, target);
+            }
+        }
+        return map;
+    }
+
+    // First page in the folder within the folder's own version scope. A folder outside
+    // every version (e.g. /docs holding v1/ and v2/) prefers its unversioned pages, as
+    // the sidebar does, then falls back to the latest version.
+    private string? FolderTarget(string folderUrl)
+    {
+        var scope = _versions.FindContaining(folderUrl);
+        var page = _graph.FirstPageUnder(folderUrl, p => _versions.FindContaining(p.Url)?.Id == scope?.Id);
+        if (page is not null) return page.Url;
+        if (scope is null && _versions.Current(folderUrl) is { } fallback && _versions.Versions.Any(v => UrlPath.IsUnder(v.RootUrl, folderUrl)))
+            return _versions.GetVersionHref(null, fallback);
+        return null;
+    }
+
+    private static string Parent(string url)
+    {
+        var u = UrlPath.Normalize(url);
+        var slash = u.LastIndexOf('/');
+        return slash <= 0 ? "/" : u[..slash];
+    }
+}
diff --git a/src/ShellDocs.Components/ServiceCollectionExtensions.cs b/src/ShellDocs.Components/ServiceCollectionExtensions.cs
index 0e079b6..e2073a0 100644
--- a/src/ShellDocs.Components/ServiceCollectionExtensions.cs
+++ b/src/ShellDocs.Components/ServiceCollectionExtensions.cs
@@ -1,3 +1,4 @@
+using Microsoft.AspNetCore.Hosting;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Logging;
 using ShellDocs.Components.Chrome;
@@ -44,6 +45,9 @@ public static IServiceCollection AddShellDocs(this IServiceCollection services,
         });
         services.AddSingleton<SearchIndex>(sp => SearchIndex.FromGraph(sp.GetRequiredService<NavigationGraph>()));
         services.AddSingleton<DocsVersionResolver>();
+        services.AddSingleton<DocsRedirects>();
+        if (options.EnableRedirects)
+            services.AddTransient<IStartupFilter, DocsRedirectStartupFilter>();
 
         return services;
     }
diff --git a/src/ShellDocs.Components/ShellDocs.Components.csproj b/src/ShellDocs.Components/ShellDocs.Components.csproj
index 957f09f..d2310d5 100644
--- a/src/ShellDocs.Components/ShellDocs.Components.csproj
+++ b/src/ShellDocs.Components/ShellDocs.Components.csproj
@@ -6,8 +6,9 @@
     <Description>Blazor RCL for ShellDocs: DocsLayout, sidebar, header, search, TOC, version and package selectors, plus content primitives (Callout, Card, Steps, Tabs, CodeGroup, FileTree, TypeTable, live component previews).</Description>
   </PropertyGroup>
 
+  <!-- Server-side: content is read from disk, and redirects run as middleware. -->
   <ItemGroup>
-    <SupportedPlatform Include="browser" />
+    <FrameworkReference Include="Microsoft.AspNetCore.App" />
     <InternalsVisibleTo Include="ShellDocs.Tests" />
   </ItemGroup>
 
@@ -15,8 +16,6 @@
     <ProjectReference Include="..\ShellDocs.Core\ShellDocs.Core.csproj" />
     <ProjectReference Include="..\ShellDocs.Markdown\ShellDocs.Markdown.csproj" />
     <ProjectReference Include="..\ShellDocs.Tokens\ShellDocs.Tokens.csproj" />
-    <PackageReference Include="Microsoft.AspNetCore.Components.Web" />
-    <PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" />
     <PackageReference Include="ShellIcons.Blazor" />
     <!-- ShellUI.Components ref lands once shellui is published to NuGet. -->
     <!-- <PackageReference Include="ShellUI.Components" /> -->
diff --git a/src/ShellDocs.Components/ShellDocsOptions.cs b/src/ShellDocs.Components/ShellDocsOptions.cs
index d8d3a2d..6e2e1c2 100644
--- a/src/ShellDocs.Components/ShellDocsOptions.cs
+++ b/src/ShellDocs.Components/ShellDocsOptions.cs
@@ -33,6 +33,12 @@ public class ShellDocsOptions
     // Fewer than 2 hides the version selector; any entry scopes sidebar, prev/next,
     // search and breadcrumb to the current version.
     public List<DocsVersion> Versions { get; } = new();
+    /* Redirects for URLs that aren't pages: content folders and version roots go to
+       their first page, unversioned URLs that exist in the latest version go there,
+       plus AddRedirect rules. Served by middleware that AddShellDocs registers, and
+       written as redirect pages by `shelldocs build`. */
+    public bool EnableRedirects { get; set; } = true;
+    public List<DocsRedirectRule> Redirects { get; } = new();
     // Searched recursively for X.razor to show as <DemoPreview Component="X" />'s source.
     public string? DemoSourceRoot { get; set; }
     public List<Type> RegisteredComponents { get; } = new();
@@ -130,6 +136,16 @@ private static IEnumerable<Type> DiscoverComponentTypes(Assembly assembly)
         }
     }
 
+    // Segment-aware prefix rule: AddRedirect("/docs/v0.3.0", "/docs/v0.3") also sends
+    // /docs/v0.3.0/intro to /docs/v0.3/intro. Permanent rules answer 301, others 302.
+    public ShellDocsOptions AddRedirect(string from, string to, bool permanent = true)
+    {
+        if (string.IsNullOrWhiteSpace(from) || string.IsNullOrWhiteSpace(to))
+            throw new ArgumentException("Redirect paths must be non-empty.");
+        Redirects.Add(new DocsRedirectRule(from, to, permanent));
+        return this;
+    }
+
     public ShellDocsOptions AddNavLink(string label, string href)
     {
         PrimaryNav.Add(new NavLink(label, href));
@@ -228,6 +244,8 @@ public record DocsPackage(string Id, string Title, string Description, string Ro
 
 public record DocsVersion(string Id, string Label, string RootUrl, string? Description, bool IsLatest);
 
+public record DocsRedirectRule(string From, string To, bool Permanent = true);
+
 public enum ShellDocsTheme
 {
     Shadcn,
diff --git a/src/ShellDocs.Core/NavigationGraph.cs b/src/ShellDocs.Core/NavigationGraph.cs
index 6762cde..649eab3 100644
--- a/src/ShellDocs.Core/NavigationGraph.cs
+++ b/src/ShellDocs.Core/NavigationGraph.cs
@@ -86,6 +86,22 @@ private void IndexHidden(NavigationNode node)
     public NavigationNode? FirstPageUnder(string urlPrefix)
         => _flatPages.FirstOrDefault(p => UrlPath.IsUnder(p.Url, urlPrefix));
 
+    public NavigationNode? FirstPageUnder(string urlPrefix, Func<NavigationNode, bool> predicate)
+        => _flatPages.FirstOrDefault(p => UrlPath.IsUnder(p.Url, urlPrefix) && predicate(p));
+
+    // URL of every visible content folder below the root. Empty for graphs built without on-disk paths.
+    public IEnumerable<(string Url, NavigationNode Node)> Folders()
+    {
+        if (string.IsNullOrEmpty(Root.Path)) yield break;
+        foreach (var n in FlattenFrom(Root))
+        {
+            if (n.Kind != NodeKind.Section || n == Root || string.IsNullOrEmpty(n.Path)) continue;
+            var rel = System.IO.Path.GetRelativePath(Root.Path, n.Path).Replace('\\', '/');
+            if (rel.StartsWith("..", StringComparison.Ordinal)) continue;
+            yield return (UrlPath.Normalize(rel), n);
+        }
+    }
+
     public IReadOnlyList<NavigationNode> GetBreadcrumb(NavigationNode node)
     {
         var chain = new List<NavigationNode>();
diff --git a/tests/ShellDocs.Tests/RedirectTests.cs b/tests/ShellDocs.Tests/RedirectTests.cs
new file mode 100644
index 0000000..7d6a73c
--- /dev/null
+++ b/tests/ShellDocs.Tests/RedirectTests.cs
@@ -0,0 +1,203 @@
+using System.Reflection;
+using System.Text.Json;
+using Microsoft.AspNetCore.Hosting;
+using Microsoft.AspNetCore.Http;
+using Microsoft.Extensions.DependencyInjection;
+using ShellDocs.Components;
+using ShellDocs.Core;
+using Xunit;
+
+namespace ShellDocs.Tests;
+
+// content/docs: introduction, guides/{setup,deploy}, and versions v1 (older) and
+// v2.0 (latest), ordered by meta.json. Some pages exist only in v2.0.
+public class RedirectTests : IDisposable
+{
+    private readonly string _root;
+
+    public RedirectTests()
+    {
+        _root = Path.Combine(Path.GetTempPath(), "shelldocs-redirect-" + Guid.NewGuid().ToString("N"));
+        Write("docs/introduction.md", "Intro");
+        Write("docs/guides/setup.md", "Setup");
+        Write("docs/guides/deploy.md", "Deploy");
+        foreach (var v in new[] { "v1", "v2.0" })
+        {
+            Write($"docs/{v}/getting-started.md", $"Start {v}");
+            Write($"docs/{v}/cli/build.md", $"Build {v}");
+        }
+        Write("docs/v2.0/cli/dev.md", "Dev");
+        Meta("docs", "introduction", "guides");
+        Meta("docs/guides", "setup", "deploy");
+        Meta("docs/v1", "getting-started", "cli");
+        Meta("docs/v2.0", "getting-started", "cli");
+    }
+
+    private void Meta(string folder, params string[] pages)
+        => File.WriteAllText(Path.Combine(_root, folder.Replace('/', Path.DirectorySeparatorChar), "meta.json"),
+            JsonSerializer.Serialize(new { pages }));
+
+    public void Dispose()
+    {
+        try { Directory.Delete(_root, recursive: true); } catch { }
+    }
+
+    private void Write(string rel, string body)
+    {
+        var path = Path.Combine(_root, rel.Replace('/', Path.DirectorySeparatorChar));
+        Directory.CreateDirectory(Path.GetDirectoryName(path)!);
+        File.WriteAllText(path, $"---\ntitle: {Path.GetFileNameWithoutExtension(rel)}\n---\n{body}\n");
+    }
+
+    private DocsRedirects Redirects(Action<ShellDocsOptions>? configure = null)
+    {
+        var options = new ShellDocsOptions { ContentRoot = _root };
+        options.AddVersion("v2.0", "v2.0", "/docs/v2.0", "Latest", latest: true);
+        options.AddVersion("v1", "v1", "/docs/v1", "Older");
+        configure?.Invoke(options);
+        var graph = NavigationGraphBuilder.Build(_root);
+        return new DocsRedirects(options, graph, new DocsVersionResolver(options, graph));
+    }
+
+    [Fact]
+    public void VersionRoots_GoToTheVersionsFirstPage_IncludingDottedOnes()
+    {
+        var r = Redirects();
+        Assert.Equal("/docs/v2.0/getting-started", r.Resolve("/docs/v2.0")?.Url);
+        Assert.Equal("/docs/v1/getting-started", r.Resolve("/docs/v1/")?.Url);
+        Assert.False(r.Resolve("/docs/v2.0")!.Permanent);
+    }
+
+    [Fact]
+    public void Folders_GoToTheirFirstPage_AndTheDocsRootPrefersUnversionedPages()
+    {
+        var r = Redirects();
+        Assert.Equal("/docs/guides/setup", r.Resolve("/docs/guides")?.Url);
+        Assert.Equal("/docs/v2.0/cli/build", r.Resolve("/docs/v2.0/cli")?.Url);
+        Assert.Equal("/docs/introduction", r.Resolve("/docs")?.Url);
+    }
+
+    [Fact]
+    public void DocsRoot_FallsBackToTheLatestVersion_WhenEverythingIsVersioned()
+    {
+        File.Delete(Path.Combine(_root, "docs", "introduction.md"));
+        Directory.Delete(Path.Combine(_root, "docs", "guides"), recursive: true);
+
+        Assert.Equal("/docs/v2.0/getting-started", Redirects().Resolve("/docs")?.Url);
+    }
+
+    [Fact]
+    public void UnversionedUrls_GoToTheLatestVersion()
+    {
+        var r = Redirects();
+        Assert.Equal("/docs/v2.0/cli/dev", r.Resolve("/docs/cli/dev")?.Url);
+        Assert.Equal("/docs/v2.0/getting-started", r.Resolve("/docs/getting-started")?.Url);
+        Assert.Equal("/docs/v2.0/cli/build", r.Resolve("/docs/cli")?.Url);
+    }
+
+    [Fact]
+    public void Pages_AndUnknownUrls_AreLeftAlone()
+    {
+        var r = Redirects();
+        Assert.Null(r.Resolve("/docs/introduction"));
+        Assert.Null(r.Resolve("/docs/v1/cli/build"));
+        Assert.Null(r.Resolve("/docs/nope"));
+        Assert.Null(r.Resolve("/"));
+        Assert.Null(r.Resolve("/_framework/blazor.web.js"));
+    }
+
+    [Fact]
+    public void Rules_ArePrefixes_AndChainIntoComputedRedirects()
+    {
+        var r = Redirects(o => o.AddRedirect("/docs/v2.0.0", "/docs/v2.0").AddRedirect("/docs", "/docs/v2.0", permanent: false));
+
+        var page = r.Resolve("/docs/v2.0.0/cli/dev");
+        Assert.Equal("/docs/v2.0/cli/dev", page?.Url);
+        Assert.True(page!.Permanent);
+
+        var root = r.Resolve("/docs/v2.0.0");
+        Assert.Equal("/docs/v2.0/getting-started", root?.Url);
+        Assert.False(root!.Permanent);
+
+        // A rule whose target is inside its source doesn't loop.
+        Assert.Null(r.Resolve("/docs/v2.0/cli/dev"));
+    }
+
+    [Fact]
+    public void All_ListsComputedAndRuleRedirects_AndNeverAPage()
+    {
+        var r = Redirects(o => o.AddRedirect("/docs/old", "/docs/guides"));
+        var all = r.All().ToDictionary(x => x.From, x => x.To, StringComparer.OrdinalIgnoreCase);
+
+        Assert.Equal("/docs/v2.0/getting-started", all["/docs/v2.0"]);
+        Assert.Equal("/docs/v2.0/cli/dev", all["/docs/cli/dev"]);
+        Assert.Equal("/docs/guides/deploy", all["/docs/old/deploy"]);
+        Assert.DoesNotContain("/docs/introduction", all.Keys);
+        Assert.DoesNotContain("/docs/v1/cli/build", all.Keys);
+    }
+
+    [Fact]
+    public async Task Middleware_Redirects_AndServesTheMap()
+    {
+        var r = Redirects(o => o.AddRedirect("/docs/old", "/docs/guides"));
+        var reachedNext = false;
+        var middleware = Activator.CreateInstance(MiddlewareType(), (RequestDelegate)(_ => { reachedNext = true; return Task.CompletedTask; }), r)!;
+        var invoke = MiddlewareType().GetMethod("InvokeAsync")!;
+
+        var folder = Context("/docs/v2.0", "?tab=1", "/base");
+        await (Task)invoke.Invoke(middleware, [folder])!;
+        Assert.Equal(302, folder.Response.StatusCode);
+        Assert.Equal("/base/docs/v2.0/getting-started?tab=1", folder.Response.Headers.Location.ToString());
+
+        var moved = Context("/docs/old/setup");
+        await (Task)invoke.Invoke(middleware, [moved])!;
+        Assert.Equal(301, moved.Response.StatusCode);
+
+        var page = Context("/docs/introduction");
+        await (Task)invoke.Invoke(middleware, [page])!;
+        Assert.True(reachedNext);
+
+        var map = Context("/_shelldocs/redirects.json");
+        map.Response.Body = new MemoryStream();
+        await (Task)invoke.Invoke(middleware, [map])!;
+        map.Response.Body.Position = 0;
+        using var json = JsonDocument.Parse(map.Response.Body);
+        Assert.Contains(json.RootElement.EnumerateArray(), e => e.GetProperty("from").GetString() == "/docs/v2.0");
+    }
+
+    [Fact]
+    public void AddShellDocs_RegistersTheStartupFilter_UnlessDisabled()
+    {
+        var on = new ServiceCollection().AddShellDocs(o => o.ContentRoot = _root);
+        Assert.Contains(on, d => d.ServiceType == typeof(IStartupFilter));
+
+        var off = new ServiceCollection().AddShellDocs(o => { o.ContentRoot = _root; o.EnableRedirects = false; });
+        Assert.DoesNotContain(off, d => d.ServiceType == typeof(IStartupFilter));
+    }
+
+    [Fact]
+    public void BuildRedirectPage_IsBaseRelative()
+    {
+        var cli = AppDomain.CurrentDomain.GetAssemblies().FirstOrDefault(a => a.GetName().Name == "shelldocs") ?? Assembly.Load("shelldocs");
+        var page = (string)cli.GetType("ShellDocs.CLI.Commands.PrerenderRunner", throwOnError: true)!
+            .GetMethod("RedirectPage", BindingFlags.Static | BindingFlags.NonPublic | BindingFlags.Public)!
+            .Invoke(null, ["/docs/v2.0/getting-started"])!;
+
+        Assert.Contains("<base href=\"/\" />", page);
+        Assert.Contains("url=docs/v2.0/getting-started", page);
+        Assert.Contains("\"docs/v2.0/getting-started\"", page);
+        Assert.Contains("noindex", page);
+    }
+
+    private static Type MiddlewareType() => typeof(DocsRedirects).Assembly.GetType("ShellDocs.Components.DocsRedirectMiddleware", throwOnError: true)!;
+
+    private static DefaultHttpContext Context(string path, string query = "", string pathBase = "")
+    {
+        var ctx = new DefaultHttpContext();
+        ctx.Request.Method = "GET";
+        ctx.Request.Path = path;
+        ctx.Request.PathBase = pathBase;
+        ctx.Request.QueryString = new QueryString(query);
+        return ctx;
+    }
+}

From d80abbe4bc027e0eec1c3f0e08e8bac1220b7bb3 Mon Sep 17 00:00:00 2001
From: Shewart <shewartshepherd23@gmail.com>
Date: Fri, 2 Oct 2026 22:23:29 +0200
Subject: [PATCH 3/5] fix(cli): fill in content files that publish left out

A csproj with <Content Update="content/**/*.md"> publishes meta.json but no markdown, and build only mirrored content/ when the folder was missing entirely, so every page prerendered as "Page not found". Build now merges in any source content file publish didn't copy. The example project had exactly this csproj; it now uses Content Include like the init scaffold.
---
 .../ShellDocs.Preview.csproj                  |  3 +-
 src/ShellDocs.CLI/Commands/BuildCommand.cs    | 30 +++++++------------
 2 files changed, 12 insertions(+), 21 deletions(-)

diff --git a/examples/ShellDocs.Preview/ShellDocs.Preview.csproj b/examples/ShellDocs.Preview/ShellDocs.Preview.csproj
index f9a1401..0aabee7 100644
--- a/examples/ShellDocs.Preview/ShellDocs.Preview.csproj
+++ b/examples/ShellDocs.Preview/ShellDocs.Preview.csproj
@@ -12,7 +12,8 @@
   </ItemGroup>
 
   <ItemGroup>
-    <Content Update="content/**/*.md;content/**/meta.json" CopyToOutputDirectory="PreserveNewest" />
+    <Content Include="content/**/*.md" CopyToOutputDirectory="PreserveNewest" CopyToPublishDirectory="PreserveNewest" />
+    <Content Update="content/**/meta.json" CopyToOutputDirectory="PreserveNewest" CopyToPublishDirectory="PreserveNewest" />
     <!-- <DemoPreview> reads these at runtime. The Razor SDK drops .razor files from
              publish even with Content metadata, so ship them as None items. -->
     <None Include="Demos/**/*.razor" CopyToOutputDirectory="PreserveNewest" CopyToPublishDirectory="PreserveNewest" />
diff --git a/src/ShellDocs.CLI/Commands/BuildCommand.cs b/src/ShellDocs.CLI/Commands/BuildCommand.cs
index 1a372a8..1030de7 100644
--- a/src/ShellDocs.CLI/Commands/BuildCommand.cs
+++ b/src/ShellDocs.CLI/Commands/BuildCommand.cs
@@ -39,14 +39,14 @@ public static int Run(string dir, string output, string? baseHref, bool spaFallb
         var publishExit = RunPublish(csproj, publishStage);
         if (publishExit != 0) return publishExit;
 
-        // Mirror content/ into publish: csprojs using `<Content Update="content/...">`
-        // don't copy .md files, which would prerender every page as "Page not found".
+        // Fill in content/ files publish left out: csprojs using `<Content Update="content/...">`
+        // copy meta.json but not .md files, which would prerender every page as "Page not found".
         var publishContent = Path.Combine(publishStage, "content");
-        if (!Directory.Exists(publishContent))
-        {
-            AnsiConsole.MarkupLine("[dim]content:[/] publish output has no content/ — mirroring from source");
-            CopyDirectoryOverwriting(contentRoot, publishContent);
-        }
+        var published = CountFiles(publishContent);
+        CopyDirectoryMerging(contentRoot, publishContent);
+        var filledIn = CountFiles(publishContent) - published;
+        if (filledIn > 0)
+            AnsiConsole.MarkupLine($"[dim]content:[/] copied [cyan]{filledIn}[/] file(s) from content/ that publish left out");
 
         // Home ("/") is served by Home.razor and isn't part of NavigationGraph.
         var urls = new List<string> { "/" };
@@ -136,6 +136,9 @@ private static int RunPublish(string csproj, string publishDir)
     }
 
     // Never overwrites — protects prerendered HTML sitting in the output tree.
+    private static int CountFiles(string dir)
+        => Directory.Exists(dir) ? Directory.GetFiles(dir, "*", SearchOption.AllDirectories).Length : 0;
+
     internal static void CopyDirectoryMerging(string source, string dest)
     {
         Directory.CreateDirectory(dest);
@@ -150,19 +153,6 @@ internal static void CopyDirectoryMerging(string source, string dest)
         }
     }
 
-    internal static void CopyDirectoryOverwriting(string source, string dest)
-    {
-        Directory.CreateDirectory(dest);
-        foreach (var file in Directory.GetFiles(source))
-        {
-            File.Copy(file, Path.Combine(dest, Path.GetFileName(file)), overwrite: true);
-        }
-        foreach (var subdir in Directory.GetDirectories(source))
-        {
-            CopyDirectoryOverwriting(subdir, Path.Combine(dest, Path.GetFileName(subdir)));
-        }
-    }
-
     // `baseHref` must include leading + trailing slashes ("/repo-name/").
     internal static int RewriteBaseHrefInAllHtml(string outputDir, string baseHref)
     {

From d89e8a5fb77d851d66905a6cc8ab39a1873c1bad Mon Sep 17 00:00:00 2001
From: Shewart <shewartshepherd23@gmail.com>
Date: Fri, 2 Oct 2026 22:23:30 +0200
Subject: [PATCH 4/5] feat(content): render the frontmatter title as the page
 header

ShellDocsOptions.RenderPageTitle renders frontmatter title as the page heading and description as a lead paragraph when the markdown body doesn't start with its own # heading, so pages don't need a manual H1. Off by default.
---
 .../Content/MarkdownContent.razor             | 32 +++++++++++++++
 src/ShellDocs.Components/ShellDocsOptions.cs  |  3 ++
 .../wwwroot/shelldocs-theme.css               |  5 +++
 tests/ShellDocs.Tests/PageTitleTests.cs       | 41 +++++++++++++++++++
 4 files changed, 81 insertions(+)
 create mode 100644 tests/ShellDocs.Tests/PageTitleTests.cs

diff --git a/src/ShellDocs.Components/Content/MarkdownContent.razor b/src/ShellDocs.Components/Content/MarkdownContent.razor
index 9330a72..1354526 100644
--- a/src/ShellDocs.Components/Content/MarkdownContent.razor
+++ b/src/ShellDocs.Components/Content/MarkdownContent.razor
@@ -3,6 +3,7 @@
 @inject IJSRuntime JS
 @inject DocsPageState PageState
 @inject ILogger<MarkdownContent> Logger
+@inject ShellDocsOptions Options
 
 <div class="shelldocs-prose">
     @if (_parts is null)
@@ -13,6 +14,16 @@
     {
         @* Ordinal ids keep anchors and saved tab state stable across renders. *@
         var previewIndex = 0;
+        @if (_title is not null)
+        {
+            <header class="docs-page-header">
+                <h1>@_title</h1>
+                @if (!string.IsNullOrWhiteSpace(_description))
+                {
+                    <p class="docs-page-description">@_description</p>
+                }
+            </header>
+        }
         @foreach (var part in _parts)
         {
             @if (part is HtmlPart html)
@@ -39,14 +50,35 @@
     [Parameter] public RenderedDocument? Document { get; set; }
 
     private IReadOnlyList<RenderPart>? _parts;
+    private string? _title;
+    private string? _description;
 
     protected override void OnParametersSet()
     {
         var doc = Document ?? (Markdown is not null ? Renderer.Render(Markdown) : null);
         _parts = doc is null ? null : SlotSplitter.Split(doc);
+        _title = _description = null;
+        if (doc is not null && Options.RenderPageTitle && !StartsWithH1(doc.Source.Body))
+        {
+            _title = NonEmpty(doc.Source.Frontmatter.GetValue<string>("title"));
+            _description = _title is null ? null : NonEmpty(doc.Source.Frontmatter.GetValue<string>("description"));
+        }
         PageState.SetDocument(doc);
     }
 
+    private static bool StartsWithH1(string body)
+    {
+        foreach (var line in body.Split('\n'))
+        {
+            var t = line.Trim();
+            if (t.Length == 0) continue;
+            return t.StartsWith("# ", StringComparison.Ordinal) || t.StartsWith("<h1", StringComparison.OrdinalIgnoreCase);
+        }
+        return false;
+    }
+
+    private static string? NonEmpty(string? s) => string.IsNullOrWhiteSpace(s) ? null : s.Trim();
+
     protected override async Task OnAfterRenderAsync(bool firstRender)
     {
         if (_parts is null) return;
diff --git a/src/ShellDocs.Components/ShellDocsOptions.cs b/src/ShellDocs.Components/ShellDocsOptions.cs
index 6e2e1c2..a220e9b 100644
--- a/src/ShellDocs.Components/ShellDocsOptions.cs
+++ b/src/ShellDocs.Components/ShellDocsOptions.cs
@@ -25,6 +25,9 @@ public class ShellDocsOptions
     // Rendered as MarkupString — must be trusted content the consumer authored, not user input.
     public string? LogoSvg { get; set; }
     public ShellDocsTheme Theme { get; set; } = ShellDocsTheme.Shadcn;
+    // Renders frontmatter `title` (and `description` as a lead) as the page header
+    // when the markdown body doesn't start with its own `# Heading`.
+    public bool RenderPageTitle { get; set; }
     public DocsLayoutVariant LayoutVariant { get; set; } = DocsLayoutVariant.TopNav;
 
     public List<NavLink> PrimaryNav { get; } = new();
diff --git a/src/ShellDocs.Components/wwwroot/shelldocs-theme.css b/src/ShellDocs.Components/wwwroot/shelldocs-theme.css
index 1d92862..bd69a35 100644
--- a/src/ShellDocs.Components/wwwroot/shelldocs-theme.css
+++ b/src/ShellDocs.Components/wwwroot/shelldocs-theme.css
@@ -92,6 +92,11 @@ body { margin: 0; min-height: 100vh; }
 .shelldocs-prose hr:where(:not(.not-prose, .not-prose *)) { border: 0; border-top: 1px solid var(--border); margin: 2.5rem 0; }
 .shelldocs-prose img:where(:not(.not-prose, .not-prose *)) { border-radius: var(--radius); border: 1px solid var(--border); max-width: 100%; height: auto; }
 
+/* Page header from frontmatter (ShellDocsOptions.RenderPageTitle). */
+.docs-page-header { margin-bottom: 2rem; }
+.docs-page-header h1 { margin-bottom: 0.5rem; }
+.docs-page-header .docs-page-description { margin: 0; color: var(--muted-foreground); font-size: 1.0625rem; line-height: 1.6; }
+
 /* Code blocks — wrapped by CodeBlockEnhancer */
 .shelldocs-codeblock {
     position: relative;
diff --git a/tests/ShellDocs.Tests/PageTitleTests.cs b/tests/ShellDocs.Tests/PageTitleTests.cs
new file mode 100644
index 0000000..9037180
--- /dev/null
+++ b/tests/ShellDocs.Tests/PageTitleTests.cs
@@ -0,0 +1,41 @@
+using ShellDocs.Components.Content;
+using Xunit;
+
+namespace ShellDocs.Tests;
+
+public class PageTitleTests
+{
+    private const string WithFrontmatter = "---\ntitle: Button\ndescription: Clickable things.\n---\n\nBody text.\n";
+
+    private static Task<string> Render(string markdown, bool renderTitle) => new ComponentRenderHarness(o =>
+    {
+        o.ContentRoot = Path.Combine(Path.GetTempPath(), "shelldocs-no-content-" + Guid.NewGuid().ToString("N"));
+        o.RenderPageTitle = renderTitle;
+    }).RenderAsync<MarkdownContent>(new() { ["Markdown"] = markdown });
+
+    [Fact]
+    public async Task On_RendersTitleAndDescription_AsTheHeader()
+    {
+        var html = await Render(WithFrontmatter, renderTitle: true);
+
+        // [^>]* allows for the scoped-CSS attribute.
+        Assert.Matches("<header class=\"docs-page-header\"[^>]*>\\s*<h1[^>]*>Button</h1>", html);
+        Assert.Matches("<p class=\"docs-page-description\"[^>]*>Clickable things.</p>", html);
+    }
+
+    [Fact]
+    public async Task On_ButTheBodyHasItsOwnH1_KeepsTheBodys()
+    {
+        var html = await Render("---\ntitle: Button\n---\n\n# Buttons everywhere\n\nBody.\n", renderTitle: true);
+
+        Assert.DoesNotContain("docs-page-header", html);
+        Assert.Contains("Buttons everywhere", html);
+    }
+
+    [Fact]
+    public async Task Off_ByDefault()
+    {
+        var html = await Render(WithFrontmatter, renderTitle: false);
+        Assert.DoesNotContain("docs-page-header", html);
+    }
+}

From 2159e360e6b7532d7ffd7948afc713fffc529269 Mon Sep 17 00:00:00 2001
From: Shewart <shewartshepherd23@gmail.com>
Date: Fri, 2 Oct 2026 22:23:31 +0200
Subject: [PATCH 5/5] docs: generic components, redirects and the page title
 option

CHANGELOG Unreleased entries; README sections on redirects, generic components and RenderPageTitle; ARCHITECTURE on DocsRedirects, the middleware, generic closing and the build steps; installation and markdown-syntax pages, with a generic ValueBadge example component.
---
 CHANGELOG.md                                  |  5 ++++
 README.md                                     | 13 +++++++++--
 docs/ARCHITECTURE.md                          | 23 +++++++++++++++----
 .../ShellDocs.Preview/Ui/ValueBadge.razor     | 13 +++++++++++
 .../ShellDocs.Preview/Ui/ValueBadge.razor.css | 20 ++++++++++++++++
 .../content/docs/installation.md              |  4 +++-
 .../content/docs/markdown-syntax.md           | 16 +++++++++++++
 7 files changed, 86 insertions(+), 8 deletions(-)
 create mode 100644 examples/ShellDocs.Preview/Ui/ValueBadge.razor
 create mode 100644 examples/ShellDocs.Preview/Ui/ValueBadge.razor.css

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 336cfa3..5645f04 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,17 +8,22 @@ All notable changes to ShellDocs land here. Format follows [Keep a Changelog](ht
 
 - **Preview layout.** `razor:preview stretch` (fence info string), or `Layout="stretch"` on `<DemoPreview>` / `<ComponentPreview>` / `PreviewFrame`, lets block-level components (charts, inputs, tables) fill the frame instead of shrinking to their content. `center` stays the default.
 - **`not-prose` class.** Every `.shelldocs-prose` rule skips `.not-prose` subtrees. Preview frames carry it; add it to any element that should keep page typography out.
+- **Generic components in markdown.** `RegisterComponentsFromAssembly` now registers generic components under their bare name (`<BarChart>`), and `razor:preview`, inline tags and `<ComponentPreview>` close them from a type-parameter attribute, as Razor does: `<BarChart TItem="SalesRow" />`. Type arguments take C# spellings (`int?`, `List<string>`, full or simple type names). Without one, `object` is used when the constraints allow it (with a warning); otherwise the component renders an inline error instead of breaking the page. A non-generic component with the same name keeps the tag. `<AutoTypeTable>` lists the type parameters.
+- **Redirects.** URLs that aren't pages now redirect: content folders and version roots to their first page (`/docs` prefers unversioned pages, then the latest version), and unversioned URLs that exist in the latest version to that page (`/docs/cli/dev` → `/docs/v2.0/cli/dev`). `o.AddRedirect(from, to, permanent)` adds segment-aware prefix rules for moved content; computed redirects answer 302, rules 301. Middleware registered by `AddShellDocs` serves them before routing (so dotted version roots like `/docs/v0.2.1` work), and `shelldocs build` writes them as redirect pages. Opt out with `o.EnableRedirects = false`.
+- **`ShellDocsOptions.RenderPageTitle`.** Renders frontmatter `title` as the page heading and `description` as a lead paragraph when the body doesn't start with its own `# Heading`. Off by default.
 
 ### Changed
 
 - **`razor:preview` child content is parsed as Razor, not markdown.** Component bodies inside a fence (and `<ComponentPreview>` bodies) go through the same node parser as the fence itself: elements wrap nested components exactly as written and nothing is wrapped in `<p>`. Inline component tags in prose still take markdown bodies.
 - **`ThemeToggle` works without a Blazor runtime.** Clicks are handled by `shelldocs.js` and both icons render, with CSS picking one from `<html class="dark">`.
+- **`ShellDocs.Components` references the ASP.NET Core shared framework** (for the redirect middleware) instead of the `Microsoft.AspNetCore.Components.Web` package. It already read content from disk, so it was server-side in practice.
 
 ### Fixed
 
 - **Prose styles leaked into previews.** Paragraph margins, list padding, heading sizes and link underlines from `.shelldocs-prose` hit live components and beat Tailwind's layered utilities (gaps inside cards and menus, underlined nav links).
 - **Nested markup inside a preview component was mangled.** `<Navbar><div><a/>…<ThemeToggle/></div></Navbar>` closed the `<div>` before the nested component and wrapped loose text in `<p>`.
 - **Theme state only followed ShellDocs' own toggle.** A component library flipping `<html class="dark">` left the stored theme and `ThemeState` stale. `shelldocs.js` now watches the class, saves it under `shelldocs-theme` and pushes it into `ThemeState`.
+- **`shelldocs build` prerendered "Page not found" pages** when the csproj copied `meta.json` but not the `.md` files (`<Content Update="content/**/*.md">`). Build only mirrored `content/` when it was missing entirely; it now fills in every file publish left out. The example project's csproj is fixed too.
 - **`enhancedload` handlers never ran.** Blazor raises the event through `Blazor.addEventListener`, not as a DOM event, so re-applying the theme, re-attaching the TOC and closing the mobile nav after enhanced navigation (static SSR apps) silently did nothing.
 
 ## [0.1.9-alpha] — 2026-10-02
diff --git a/README.md b/README.md
index 627b93d..9a9021a 100644
--- a/README.md
+++ b/README.md
@@ -29,7 +29,7 @@ Already have a Blazor project? Run `shelldocs init --attach` inside it: it adds
 
 ## What you get
 
-- **Markdown-first authoring.** YAML frontmatter, Shiki-highlighted code fences, live `razor:preview` examples, inline component tags mid-prose.
+- **Markdown-first authoring.** YAML frontmatter, Shiki-highlighted code fences, live `razor:preview` examples, inline component tags mid-prose. Set `o.RenderPageTitle = true` to render the frontmatter `title` and `description` as the page header instead of writing `# Title`.
 - **File-based navigation.** Drop a `.md` in `content/docs/` and it's a page. Sidebar, breadcrumb, prev/next and TOC come from the folder tree; `meta.json` controls order, dividers, subsections and hidden pages.
 - **`Cmd+K` search** across titles, headings and page text, with body snippets. The index is built in memory at startup, so there's no external service; search needs a running Blazor app (it isn't available in the static export).
 - **Blazor-native.** Your components render as real Razor components, not iframes.
@@ -63,7 +63,15 @@ The current version is the one whose `RootUrl` prefixes the path (segment-aware)
 
 It's all server-rendered links plus `shelldocs.js`, so it works on static hosts.
 
-> Routes declared as `/docs/{*Path:nonfile}` don't match a URL whose **last** segment has a dot (`/docs/v0.2.1`). Pages below it (`/docs/v0.2.1/introduction`) are fine, and the selectors never link to a bare version root unless it has an `index.md`. If you add one, drop `:nonfile` from the route.
+### Redirects
+
+URLs that aren't pages redirect instead of 404ing: content folders and version roots go to their first page (`/docs/v0.2.1` → `/docs/v0.2.1/introduction`; `/docs` prefers unversioned pages, then the latest version), and unversioned URLs that exist in the latest version go there (`/docs/cli/dev` → `/docs/v0.3/cli/dev`). Add rules for moved content:
+
+```csharp
+o.AddRedirect("/docs/v0.3.0", "/docs/v0.3");   // also /docs/v0.3.0/x → /docs/v0.3/x (301)
+```
+
+`AddShellDocs` registers middleware that answers these before routing, so a dotted version root works even though `/docs/{*Path:nonfile}` routes can't match it. `shelldocs build` writes the same redirects as static pages. Turn it off with `o.EnableRedirects = false`.
 
 ## Component previews
 
@@ -71,6 +79,7 @@ It's all server-rendered links plus `shelldocs.js`, so it works on static hosts.
 - **`razor:preview` fences render everything.** Several sibling components, HTML wrappers (`<div class="flex gap-2">…</div>`) and text render in order inside one frame, and the Code tab shows the whole fence.
 - **Child content is Razor.** Component bodies inside a fence are parsed like the fence itself, so `<Navbar><div>…<ThemeToggle /></div></Navbar>` keeps its structure and nothing is wrapped in `<p>`.
 - **Page typography stays out.** Preview frames are `not-prose`, so prose margins, list padding and link underlines don't reach your components.
+- **Generic components work.** Set the type argument as Razor does: `<BarChart TItem="SalesRow" />`, `<DataTable TItem="int" />`. Libraries' generic components are registered under their bare name.
 - **Centred or stretched.** Examples are centred; `razor:preview stretch` (or `Layout="stretch"` on `<DemoPreview>` / `<ComponentPreview>`) lets charts, inputs and tables fill the frame.
 - **Razor-shaped attribute values work:** `Variant="ButtonVariant.Destructive"`, `@ButtonVariant.Destructive`, `@true`, `@42`, `[Flags]` values as `Bold | Italic`.
 - **Attributes a static preview can't evaluate are skipped, not fatal:** `OnClick="HandleClick"`, `@onclick`, `@bind-*`, `@ref`, non-primitive parameter types, unparseable values. Each logs a warning and the component still renders.
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index a58d07f..8dc27e2 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -54,14 +54,14 @@ Turns markdown into HTML plus typed component slots. Depends on `ShellDocs.Core`
 
 ### `ShellDocs.Components`
 
-The Razor class library everyone references. Depends on `ShellDocs.Core`, `ShellDocs.Markdown`, `ShellDocs.Tokens`, `ShellIcons.Blazor`.
+The Razor class library everyone references. Depends on `ShellDocs.Core`, `ShellDocs.Markdown`, `ShellDocs.Tokens`, `ShellIcons.Blazor` and the ASP.NET Core shared framework (it reads content from disk and runs middleware, so it's server-side).
 
 - `AddShellDocs(options)` and `ShellDocsOptions`.
 - Layouts: `DocsLayout` (`TopNav` / `Sidebar` variants), `HomeLayout`.
 - Chrome: `DocsHeader`, `DocsSidebar`, `DocsSidebarHeader`, `DocsMobileBar`, `PackageSelector`, `VersionSelector`, `DocsBreadcrumb`, `PrevNextNav`, `TableOfContents`, `SearchDialog`, `ThemeToggle`, `DocsFooter`, `BrandLogo`.
 - Content primitives (auto-registered for markdown): `Callout`, `Card`, `CardGrid`, `LinkCard`, `Steps`/`Step`, `FileTree`/`FileTreeItem`, `Tabs`/`Tab`, `CodeGroup`/`CodeTab`, `TypeTable`/`TypeRow`, `AutoTypeTable`, `ComponentPreview`, `DemoPreview`.
 - Render machinery (`[ShellDocsIgnore]`, not reachable from markdown): `MarkdownContent`, `PreviewFrame`.
-- Services: `DocsPageState` (scoped), `DocsVersionResolver` (singleton).
+- Services: `DocsPageState` (scoped), `DocsVersionResolver` and `DocsRedirects` (singletons), plus the redirect middleware.
 - `wwwroot/shelldocs.js` and `wwwroot/shelldocs-theme.css`.
 
 ### `ShellDocs.Tokens`
@@ -124,6 +124,8 @@ Placeholders plus a slot list keep everything at render time: no generated Razor
 - `ComponentSlot` → `<DynamicComponent>` with parameters from `SlotRenderer.BuildParameters`.
 - `PreviewSlot` → `<PreviewFrame Id="preview-N">`, where `SlotRenderer.RenderNodes` emits elements and components as real render-tree nodes, so wrappers keep their children under interactive re-renders.
 
+**Generic components** register under their bare name (`TypeRegistry.TagNameOf`) as open definitions. `SlotRenderer.Component` closes one per use with `GenericComponents.Close`, reading attributes named after the type parameters (`TItem="int"`, resolved from C# spellings across loaded assemblies) or falling back to `object`; one it can't close renders a `.shelldocs-render-error` element instead. A non-generic component with the same name keeps the tag.
+
 Component child markup is rendered recursively. Inline tags in prose take markdown bodies (`SlotRenderer.FromMarkup`, dedented first, since Markdig treats 4-space indentation as a code block). Inside a `razor:preview` and in `<ComponentPreview>` the body is Razor: `SlotRenderer.FromRazor` parses it with `PreviewParser` and emits real elements, so wrappers around nested components stay intact. Child tags named after a `RenderFragment` parameter (`<Icon>` → `Alert.Icon`) are routed into that slot.
 
 **Parameter coercion.** Attribute values are strings. `BuildParameters` matches them to `[Parameter]` properties case-insensitively and coerces string, bool, char, numeric primitives and enums, accepting Razor forms: a leading `@`, `@( … )`, `Type.Member` enum values, `A | B` flags, numeric suffixes, `@null`. It never throws. Anything static markup can't set is skipped with a logged warning: directive attributes, delegate/`EventCallback` parameters, unsupported types, unparseable values, unknown attributes on components without a `CaptureUnmatchedValues` catch-all, and child content on components without a plain `RenderFragment ChildContent`.
@@ -169,6 +171,16 @@ Runtime queries: `ResolveByUrl` is a case-insensitive dictionary lookup on norma
 
 All answers are computed at render time and emitted as plain `<a href>`, so prerendered pages behave identically.
 
+### Redirects
+
+`DocsRedirects` (singleton) maps URLs that aren't pages to a target, computed once from the graph and versions:
+
+- content folders and version roots → their first page, within the folder's version scope (a folder holding version folders → its first unversioned page, else the latest version's);
+- unversioned URLs that exist in the latest version → that page;
+- `AddRedirect` rules on top: segment-aware prefixes that may chain into the computed redirects. They are the only thing that can redirect an existing page.
+
+`DocsRedirectMiddleware` runs first in the pipeline (added by an `IStartupFilter`, so no `Program.cs` change) and answers 302 for computed redirects or 301 for permanent rules, keeping `PathBase` and the query string. Running before routing is what makes `/docs/v0.2.1` work. It also serves the full map at `/_shelldocs/redirects.json` for `shelldocs build`. `EnableRedirects = false` leaves it out.
+
 ---
 
 ## Search
@@ -223,11 +235,12 @@ One neutral, shadcn-shaped palette of CSS variables in `ShellDocs.Tokens/tokens.
 
 `shelldocs build`:
 
-1. `dotnet publish -c Release` into `obj/shelldocs-publish` (mirroring `content/` into it if the csproj didn't copy it).
+1. `dotnet publish -c Release` into `obj/shelldocs-publish`, then copies in any `content/` file publish left out (a csproj that copies `meta.json` but not `.md`).
 2. Builds the navigation graph and collects every URL (visible and hidden) plus `/`.
 3. `PrerenderRunner` starts the published app on a free port, requests each URL and writes `<output>/<path>/index.html`.
-4. Merges the published `wwwroot/` into the output without overwriting prerendered HTML.
-5. Optionally rewrites `<base href>` in every HTML file, copies `index.html` to `404.html`, and with `--site-url` writes `sitemap.xml`, `robots.txt` and `og:*` meta.
+4. Reads the app's redirect map and writes a redirect page for each source URL without a prerendered page (meta refresh plus `location.replace`, relative to `<base href>`).
+5. Merges the published `wwwroot/` into the output without overwriting prerendered HTML.
+6. Optionally rewrites `<base href>` in every HTML file, copies `index.html` to `404.html`, and with `--site-url` writes `sitemap.xml`, `robots.txt` and `og:*` meta.
 
 ---
 
diff --git a/examples/ShellDocs.Preview/Ui/ValueBadge.razor b/examples/ShellDocs.Preview/Ui/ValueBadge.razor
new file mode 100644
index 0000000..9c68c4a
--- /dev/null
+++ b/examples/ShellDocs.Preview/Ui/ValueBadge.razor
@@ -0,0 +1,13 @@
+@typeparam TValue
+
+@* Stand-in generic library component for exercising razor:preview type arguments. *@
+<span class="value-badge">
+    <span class="value-badge-label">@Label</span>
+    <span class="value-badge-value">@Value</span>
+    <span class="value-badge-type">@typeof(TValue).Name</span>
+</span>
+
+@code {
+    [Parameter] public string? Label { get; set; }
+    [Parameter] public TValue? Value { get; set; }
+}
diff --git a/examples/ShellDocs.Preview/Ui/ValueBadge.razor.css b/examples/ShellDocs.Preview/Ui/ValueBadge.razor.css
new file mode 100644
index 0000000..7b78c07
--- /dev/null
+++ b/examples/ShellDocs.Preview/Ui/ValueBadge.razor.css
@@ -0,0 +1,20 @@
+.value-badge {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.5rem;
+    padding: 0.35rem 0.65rem;
+    border: 1px solid var(--border);
+    border-radius: 999px;
+    font-size: 0.8125rem;
+    background: var(--card);
+}
+.value-badge-label { color: var(--muted-foreground); }
+.value-badge-value { font-weight: 600; }
+.value-badge-type {
+    font-family: var(--font-mono);
+    font-size: 0.7rem;
+    color: var(--muted-foreground);
+    padding: 0.05rem 0.4rem;
+    border-radius: 999px;
+    background: var(--muted);
+}
diff --git a/examples/ShellDocs.Preview/content/docs/installation.md b/examples/ShellDocs.Preview/content/docs/installation.md
index f85a974..f25c3e7 100644
--- a/examples/ShellDocs.Preview/content/docs/installation.md
+++ b/examples/ShellDocs.Preview/content/docs/installation.md
@@ -55,4 +55,6 @@ shelldocs build
 - `--spa-fallback` copies `index.html` to `404.html`.
 - `--site-url https://docs.example.com` emits `sitemap.xml`, `robots.txt` and `og:` meta tags.
 
-In the static output, navigation, sidebar sections, the mobile menu, the version and package selectors, tabs, preview tabs and menus, the table of contents, the theme toggle and code copy all work through `shelldocs.js`. Search, the desktop sidebar-collapse button and stateful demo components still need a running Blazor app (Server or WebAssembly).
+In the static output, navigation, sidebar sections, the mobile menu, the version and package selectors, tabs, preview tabs and menus, the table of contents, the theme toggle and code copy all work through `shelldocs.js`. Search, the desktop sidebar-collapse button and stateful demo components still need a running Blazor Server app (interactive server rendering).
+
+URLs that aren't pages (folders, version roots, unversioned URLs that moved into a version) become redirect pages in the static output, the same redirects the running app answers.
diff --git a/examples/ShellDocs.Preview/content/docs/markdown-syntax.md b/examples/ShellDocs.Preview/content/docs/markdown-syntax.md
index e21dcfa..f3cb1b4 100644
--- a/examples/ShellDocs.Preview/content/docs/markdown-syntax.md
+++ b/examples/ShellDocs.Preview/content/docs/markdown-syntax.md
@@ -21,6 +21,8 @@ order: 10
 ---
 ```
 
+With `o.RenderPageTitle = true`, ShellDocs renders `title` as the page's heading and `description` as a lead paragraph, so pages don't need a `# Title` line. A page whose body starts with its own `# Heading` keeps it.
+
 ## Standard markdown works
 
 Headings, lists, tables, code fences, images, links — all standard:
@@ -72,3 +74,17 @@ Examples are centred. Add `stretch` to the info string (`razor:preview stretch`)
 ```
 
 Preview frames are marked `not-prose`, so the page's typography (paragraph margins, list padding, link underlines) never reaches the components inside. Add the class to any other element that should opt out.
+
+### Generic components
+
+Generic components (`@typeparam TValue`) register under their bare name. Set the type argument the way Razor does, as an attribute named after the type parameter. Attribute values are then coerced to the closed type:
+
+```razor:preview
+<div style="display: flex; gap: 0.75rem; flex-wrap: wrap;">
+    <ValueBadge TValue="int" Label="Downloads" Value="1200" />
+    <ValueBadge TValue="decimal" Label="Price" Value="9.99" />
+    <ValueBadge TValue="string" Label="Status" Value="stable" />
+</div>
+```
+
+Type arguments accept C# spellings (`int`, `int?`, `List<string>`, `MyApp.Models.Product`). Without one, ShellDocs uses `object` when the constraints allow it and logs a warning; a type it can't resolve shows an inline error. `<ComponentPreview Component="ValueBadge" TValue="int" … />` works the same way.