Spillgebees.Blazor.Docs.Sdk

A Razor Class Library NuGet package for building and deploying documentation sites for Spillgebees Blazor component libraries. Each component repo hosts its own docs site by referencing this SDK, without a combined repo or companion PRs.

Features

• Shell layout with collapsible sidebar, top bar, and footer
• Dark/light theme toggle with localStorage persistence
• Live component rendering alongside syntax-highlighted source code via ExampleView
• Auto-generated API reference pages from XML doc comments and reflection
• Build-time source extraction and API manifest generation via MSBuild targets (runs automatically for direct package consumers)
• Self-hosted Inter Variable and JetBrains Mono fonts
• Reusable GitHub Actions workflow for deploying to GitHub Pages

Package Sources

This package is published to nuget.org. No special feed configuration is needed.

Quick Start

1. Install the NuGet package

<PackageReference Include="Spillgebees.Blazor.Docs.Sdk" />

2. Add a ProjectReference to your library

<Project Sdk="Microsoft.NET.Sdk.BlazorWebAssembly">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Spillgebees.Blazor.Docs.Sdk" />
    <ProjectReference Include="../YourLibrary/YourLibrary.csproj" />
    <ProjectReference Include="../YourLibrary.Samples.Shared/YourLibrary.Samples.Shared.csproj" />
  </ItemGroup>
</Project>

3. Create MainLayout.razor with DocSite

@inherits LayoutComponentBase

<DocSite ProjectName="Your.Library"
         LogoEmoji="🍓"
         GitHubUrl="https://github.com/Spillgebees/Your.Library"
         Navigation="@Navigation">
    @Body
</DocSite>

@code {
    private static readonly NavSection[] Navigation =
    [
        new("Getting Started", [
            new NavPage("Home", ""),
            new NavPage("Installation", "installation"),
        ]),
        new("Components", [
            new NavPage("MyComponent", "components/my-component"),
        ]),
        new("API Reference", ApiReferenceNav.Generate<MyComponent>()),
    ];
}

4. Add the CSS link to wwwroot/index.html

<link rel="stylesheet" href="_content/Spillgebees.Blazor.Docs.Sdk/docs-sdk.css" />

5. Create pages with @page directives

@page "/installation"

<h1>Installation</h1>
<p>Add the NuGet package to your project.</p>

Components

Component	Description
DocSite	Root layout component wrapping the entire app with sidebar, top bar, and footer
ExampleView	Renders a live Blazor component alongside its build-time-extracted, syntax-highlighted source code
CodeBlock	Displays a syntax-highlighted code snippet with a copy-to-clipboard button
ApiDoc	Auto-generated API documentation page for a type, sourced from XML doc comments and reflection
ThemeToggle	Switches between dark and light mode and persists the preference to localStorage
DocSidebar	Collapsible navigation sidebar driven by the Navigation parameter on DocSite
DocFooter	Footer displaying the GitHub link configured on DocSite

Build-Time Automation

When your docs project directly references the SDK package, MSBuild targets run automatically during build:

Source extraction scans your Razor files for ExampleView<TComponent> references, locates the matching .razor and .razor.cs source files in referenced projects, and embeds them as assembly resources. ExampleView reads these at runtime to display syntax-highlighted source alongside live components.

API manifest generation reflects over referenced Spillgebees library assemblies and their XML documentation files to produce a JSON manifest. ApiDoc and ApiReferenceNav.Generate<T>() use this manifest to render API reference pages with parameters, methods, events, and descriptions.

At runtime, ExampleView, ApiDoc, and ApiReferenceNav.Generate<T>() search for embedded resources across all loaded assemblies — the library assembly is checked first, then the docs project assembly and others. This means the resources work regardless of which assembly they end up in.

No configuration needed. The targets only run in projects that directly reference the SDK (packed into build/, not buildTransitive/), so transitive consumers are unaffected.

Running the Demo

dotnet run --project samples/Spillgebees.Blazor.Docs.Sdk.Demo/

Deployment

The SDK provides a reusable GitHub Actions workflow at .github/workflows/deploy-docs.yml for deploying to GitHub Pages. Consuming repos reference it as follows:

# .github/workflows/deploy-docs.yml (in the consuming repo)
name: Deploy Docs

on:
  push:
    branches: [main]

jobs:
  deploy:
    uses: Spillgebees/Blazor.Docs.Sdk/.github/workflows/deploy-docs.yml@main
    with:
      docs-project-path: src/Docs/Docs.csproj
      base-href: /Your.Library/

The workflow publishes the WASM app, patches the <base href> for the GitHub Pages subpath, and deploys to spillgebees.github.io/{repo-name}/.

License

MIT