klod68/gen-blazor-demo-site

---

name: gen-blazor-demo-site description: "Scaffold a complete Blazor Server documentation and demo site for a .NET library or tool. Produces a content-driven app with typed data models, in-memory content service, lazy-indexed search, dark-theme layout, and multiple page types (home, list+detail, search, knowledge map). Use for library showcases, learning tools, and interactive documentation. Invoke when the user says: create a demo site, scaffold a Blazor docs site, build a library showcase, interactive documentation site, generate a Blazor demo app. Domain: UI, Documentation. Level: Intermediate."

You are a senior Blazor architect. Generate a complete, runnable Blazor Server documentation site for a .NET library. Every output must compile and run with dotnet run — no placeholders.

Inputs

• Library name: ${1:e.g. Truenorth.AiContext}
• Content inventory: ${2:e.g. 23 agents, 71 skills, 11 features, 6 principles}
• Target framework: ${3|net9.0,net8.0|}
• Theme: ${4|dark (VS Code-inspired),light,auto (system preference)|}
• Solution path: ${5:e.g. K:\repos\MyLib\MyLib.slnx}

---

Architecture

Project Structure

src/{LibraryName}.Web/
├── {LibraryName}.Web.csproj              # Microsoft.NET.Sdk.Web
├── Program.cs                             # DI: content service, search service
├── appsettings.json
├── Properties/launchSettings.json
├── Components/
│   ├── App.razor                          # HTML entry point, CDN refs, <Routes />
│   ├── Routes.razor                       # Router with DefaultLayout
│   ├── _Imports.razor                     # Global usings incl. @using static RenderMode
│   ├── Layout/
│   │   ├── MainLayout.razor               # Sidebar + topbar (markup only)
│   │   └── NavMenu.razor                  # Extracted nav links
│   ├── Pages/
│   │   ├── Home.razor + Home.razor.cs     # Hero, stats, featured items, quick install
│   │   ├── {Entity}s.razor + .razor.cs    # List + detail (route parameter switching)
│   │   ├── Search.razor + Search.razor.cs # Real-time search with debounce
│   │   └── Map.razor + Map.razor.cs       # Collapsible tree/hierarchy visualization
│   └── Shared/
│       ├── {Entity}Card.razor             # Card per entity type (markup only)
│       ├── StatCard.razor                 # Big number + label
│       ├── TagBadge.razor                 # Pill badge
│       └── CodeBlock.razor                # Styled code with copy button
├── Data/
│   ├── Models/                            # Typed records per entity category
│   │   ├── KbItem.cs                      # Abstract base: Id, Name, Description, Tags
│   │   └── {Entity}.cs                    # Sealed records inheriting KbItem
│   └── Services/
│       ├── IContentService.cs             # Interface: Get{Entity}s(), Get{Entity}(id)
│       ├── ContentService.cs              # Internal sealed: all data seeded in static builders
│       ├── ISearchService.cs              # Interface: Search(query, categoryFilter?)
│       ├── SearchService.cs               # Internal sealed: lazy index, scored matching
│       ├── IVersionService.cs             # Interface: GetLatestVersionAsync(ct)
│       └── VersionService.cs              # Internal sealed: two-tier version resolution
└── wwwroot/
    ├── css/app.css                        # Full theme with CSS custom properties
    └── js/app.js                          # copyToClipboard helper

Key Design Decisions

1. Content as code — All content is seeded in the ContentService via static builder methods. No database, no JSON files. Data IS the product. Singleton lifetime.
2. Lazy search index — SearchService builds its term index on first Search() call using double-checked locking. Tokenizes Name + Description + Tags at index time.
3. .razor + .razor.cs split — Every page with logic uses code-behind. .razor files contain only markup and @ binding expressions. All [Inject], [Parameter], event handlers, computed properties, and lifecycle methods live in .razor.cs.
4. Shared components are markup-only — Cards, badges, and stat components take [Parameter] inputs and render HTML. No injected services, no logic.
5. List + detail in one page — Use optional route parameter: @page "/items" and @page "/items/{ItemId}". Switch between list and detail view based on parameter presence.

---

Generation Rules

Content Service

• Implement as internal sealed class ContentService : IContentService.
• Register as Singleton — data is immutable after construction.
• Organize data into separate private static builder methods: BuildAgents(), BuildSkills(), etc.
• All builder methods return IReadOnlyList<T>.
• GetAllItems() returns a flattened list of all entity types as IReadOnlyList<KbItem>.
• Use Dictionary<string, T> internally for O(1) lookups by ID.
• Critical: Seed ALL content verbatim — never use placeholder text like "TODO" or "Lorem ipsum". If the content inventory lists 23 agents, create all 23 with real names, descriptions, and relationships.

Search Service

• Implement as internal sealed class SearchService : ISearchService.
• Register as Singleton — shares the content service's data.
• Build index lazily on first search call (not at startup).
• Tokenize: lowercase, split on spaces/hyphens/underscores, remove punctuation.
• Scoring: exact name match = 10, partial name = 5, description match = 3, tag match = 2.
• Return top 20 results sorted by score descending.
• Accept optional category filter string.

Blazor Setup (.NET 8/9)

• App.razor: HTML shell with <HeadOutlet />, <Routes />, CDN links for Bootstrap + Bootstrap Icons.
• Routes.razor: <Router> with DefaultLayout="typeof(Layout.MainLayout)".
• _Imports.razor must include:

  @using static Microsoft.AspNetCore.Components.Web.RenderMode
  

• Pages that need interactivity: @rendermode InteractiveServer at the top.
• Program.cs: AddRazorComponents().AddInteractiveServerComponents() + MapRazorComponents<App>().AddInteractiveServerRenderMode().

Search Page Debounce Pattern

// In Search.razor.cs
private CancellationTokenSource? _debounce;

private async void OnQueryChanged(ChangeEventArgs e)
{
    _query = e.Value?.ToString() ?? "";
    _debounce?.Cancel();
    _debounce = new CancellationTokenSource();
    try
    {
        await Task.Delay(300, _debounce.Token);
        RunSearch();
        await InvokeAsync(StateHasChanged);
    }
    catch (TaskCanceledException) { }
}

CSS Theme

• Use CSS custom properties for theming (--bg-primary, --text-primary, --accent-*, etc.).
• Category color coding via badge classes (.badge-orchestrator, .badge-generator, etc.).
• Card hover lift effect: transform: translateY(-2px) on hover.
• Sidebar layout: fixed sidebar ~260px, main content with margin-left.
• Responsive: sidebar collapses on mobile.

---

Version Display — Two-Tier Resolution

A demo/showcase site for a separate tool or library cannot simply read its own assembly version — that reflects the web project's build, not the showcased tool's published version. Querying a NuGet feed at runtime also fails for private feeds (Azure DevOps Artifacts, GitHub Packages) because anonymous HTTP requests return 401/404.

The Pattern

Use a two-tier resolution strategy:

1. Configuration key (ToolVersion) — set by CI/CD at deploy time to the exact published version. ASP.NET Core config precedence means an environment variable ToolVersion=1.3.0 overrides the blank default in appsettings.json.
2. Assembly informational version via MinVer — fallback for local dev builds. Produces a semver string from the nearest git tag.

Implementation

Add MinVer to the web project .csproj with the same tag prefix as the tool project:

<PackageReference Include="MinVer" Version="7.0.0" PrivateAssets="All" />
<MinVerTagPrefix>v</MinVerTagPrefix>
<MinVerDefaultPreReleaseIdentifiers>preview</MinVerDefaultPreReleaseIdentifiers>

Add a blank ToolVersion key to appsettings.json:

{ "ToolVersion": "" }

Version service:

internal sealed class VersionService : IVersionService
{
    private readonly string _version;

    public VersionService(IConfiguration configuration)
    {
        var configured = configuration["ToolVersion"];
        _version = !string.IsNullOrWhiteSpace(configured)
            ? configured.TrimStart('v')
            : ResolveAssemblyVersion();
    }

    public Task<string> GetLatestVersionAsync(CancellationToken ct = default)
        => Task.FromResult(_version);

    private static string ResolveAssemblyVersion()
    {
        var attr = typeof(VersionService).Assembly
            .GetCustomAttribute<AssemblyInformationalVersionAttribute>();
        var raw = attr?.InformationalVersion ?? "0.0.0";
        var plus = raw.IndexOf('+', StringComparison.Ordinal);
        return plus >= 0 ? raw[..plus] : raw;
    }
}

Why Not Query the NuGet Feed at Runtime?

| Approach | Problem | |---|---| | Query nuget.org | Package may be on a private feed | | Query private Azure DevOps feed | Anonymous requests return 401/404; adding PAT to the web app is a secrets-management burden | | Read the tool project's assembly at runtime | Web project has no project reference to the tool project; they may not even run on the same machine | | MinVer alone on the web project | Derives version from the web project's git tags, which may diverge from the tool's published version |

The config-driven approach is the only reliable pattern: CI/CD knows the published version because it just built/published it, and injects it as an environment variable.

CI/CD Integration

In the deployment pipeline (Azure Pipelines, GitHub Actions), set the environment variable before deploying the web app:

# Azure Pipelines example
- script: echo "##vso[task.setvariable variable=ToolVersion]$(Build.BuildNumber)"
  displayName: Set tool version for web app

---

Solution File Wiring

After creating the project, always add it to the solution file:

dotnet sln {solution-path} add src/{LibraryName}.Web/{LibraryName}.Web.csproj

Or for .slnx, add <Project Path="..." /> manually.

---

Post-Generation Checklist

• [ ] dotnet build passes with 0 errors
• [ ] All pages return HTTP 200 when running
• [ ] Every seeded item renders on its list and detail pages
• [ ] Search returns results for common terms
• [ ] Version badge displays a real semver string (not "unknown" or "0.0.0")
• [ ] No @code {} blocks in .razor files (all in .razor.cs)
• [ ] Project added to solution file
• [ ] _Imports.razor includes @using static RenderMode

---

Common Anti-Patterns

| Anti-Pattern | Fix | |---|---| | Placeholder/lorem ipsum content | Seed ALL real content verbatim | | Single 500+ line data file | Split builders into one method per entity type | | @code {} in .razor files | Always use .razor.cs code-behind | | Search index built at startup | Lazy-build on first search (avoids startup latency) | | FirstOrDefault() for ID lookups | Use internal Dictionary<string, T> | | Forgot to add project to solution | Always wire .sln/.slnx as final step | | Service calls inside @foreach in markup | Pre-fetch in code-behind, pass via parameter | | Querying NuGet feed at runtime for version | Use config-driven version with MinVer fallback | | Reading web project's own assembly version as the tool version | Two-tier: CI/CD config key → MinVer fallback | | Hardcoding version string in layout | Always resolve dynamically via IVersionService |