DI and middleware extension methods

The complete roster of public extension methods Pennington exposes for wiring the library into an ASP.NET Core host — Add* (DI registration), Use* (middleware and endpoints), and Run* (host entry points). Grouped below by receiver type; each method is declared in an *Extensions static class under its owning feature namespace.

`IServiceCollection` extensions

DI registration entry points. Each method's options surface is documented on its own reference page, linked from the method's xmldoc.

AddApiMetadataFromCompiledAssembly IServiceCollection AddApiMetadataFromCompiledAssembly(this IServiceCollection, Action<CompiledAssemblyApiOptions>): Package Pennington.ApiMetadata.Reflection
Convenience overload: registers under the "default" name for sites documenting a single library.
AddApiMetadataFromCompiledAssembly IServiceCollection AddApiMetadataFromCompiledAssembly(this IServiceCollection, string, Action<CompiledAssemblyApiOptions>): Package Pennington.ApiMetadata.Reflection
Registers CompiledAssemblyApiMetadataProvider as a keyed IApiMetadataProvider under name. Call once per library you want to document — each call builds its own MetadataLoadContext and xmldoc index scoped to the supplied AssemblyDirectories. The Roslyn-independent IXmlDocParser / IXmlDocHtmlRenderer shared services are registered once (idempotent).
AddApiMetadataFromRoslyn IServiceCollection AddApiMetadataFromRoslyn(this IServiceCollection, string = …, Action<ApiReferenceOptions>? = …): Package Pennington.Roslyn
Registers RoslynApiMetadataProvider as a keyed IApiMetadataProvider under name. Call once per named reference tree. Requires AddPenningtonRoslyn to have been called first with a configured SolutionPath, since the provider reads the live workspace.
AddApiReference IServiceCollection AddApiReference(this IServiceCollection, string = …, Action<ApiReferenceRegistrationOptions>? = …): Package Pennington.DocSite.Api
Registers one named API-reference tree. Call once per library you want to document. Each call pairs with a matching AddApiMetadataFrom*(name, …) provider registration and publishes its type pages at the configured RoutePrefix.
AddBlogSite IServiceCollection AddBlogSite(this IServiceCollection, Func<BlogSiteOptions>): Package Pennington.BlogSite
Registers BlogSite services with the provided options.
AddDocSite IServiceCollection AddDocSite(this IServiceCollection, Func<DocSiteOptions>): Package Pennington.DocSite
Registers DocSite services with the provided options.
AddFileWatched<T> IServiceCollection AddFileWatched<T>(this IServiceCollection): Package Pennington
Register a concrete service whose instance is managed by FileWatchDependencyFactory.
AddFileWatched<TService, TImplementation> IServiceCollection AddFileWatched<TService, TImplementation>(this IServiceCollection): Package Pennington
Register a service whose instance is managed by FileWatchDependencyFactory. The factory (singleton) recreates the instance when watched files change. The service (transient) always returns the current instance from the factory.
AddLlmsSubtree IServiceCollection AddLlmsSubtree(this IServiceCollection, LlmsSubtree): Package Pennington
Registers a LlmsSubtree so all leaves under RoutePrefix get split out into a dedicated {RoutePrefix}llms.txt. Multiple registrations are allowed; programmatic registrations override _llms.yaml-discovered subtrees with the same prefix.
AddMonorailCss IServiceCollection AddMonorailCss(this IServiceCollection, Func<IServiceProvider, MonorailCssOptions>? = …): Package Pennington.MonorailCss
Registers MonorailCSS services including the CSS class collector and stylesheet generator.
AddPennington IServiceCollection AddPennington(this IServiceCollection, Action<PenningtonOptions>): Package Pennington
Register all Pennington services.
AddPenningtonRoslyn IServiceCollection AddPenningtonRoslyn(this IServiceCollection, Action<RoslynOptions>? = …): Package Pennington.Roslyn
Add Roslyn-based code analysis and highlighting.
AddPenningtonTui IServiceCollection AddPenningtonTui(this IServiceCollection, Action<PenningtonTuiOptions>? = …): Package Pennington.Tui
Register the dev-time TUI dashboard. When the host is launched in build mode (first command-line argument is build), the hosted service no-ops and the build runs exactly as without this package.
AddSpaNavigation IServiceCollection AddSpaNavigation(this IServiceCollection, Action<SpaNavigationOptions>? = …): Package Pennington
Register SPA navigation services.

`WebApplication` and endpoint extensions

Middleware and endpoint wiring. Ordering within a Use* call chain is load-bearing; see each method's xmldoc for the invariant.

RunBlogSiteAsync Task RunBlogSiteAsync(this WebApplication, string[]): Package Pennington.BlogSite
Runs the BlogSite: either serves the app or performs a static build, based on command-line args.
RunDocSiteAsync Task RunDocSiteAsync(this WebApplication, string[]): Package Pennington.DocSite
Runs the DocSite: either serves the app or performs a static build, based on command-line args.
RunOrBuildAsync Task RunOrBuildAsync(this WebApplication, string[]): Package Pennington
Run in dev mode or build static site.
UseBlogSite WebApplication UseBlogSite(this WebApplication): Package Pennington.BlogSite
Wires BlogSite middleware, Razor components, and RSS endpoint into the request pipeline.
UseDocSite WebApplication UseDocSite(this WebApplication): Package Pennington.DocSite
Wires DocSite middleware and Razor components into the request pipeline.
UseMonorailCss WebApplication UseMonorailCss(this WebApplication, string = …): Package Pennington.MonorailCss
Maps the MonorailCSS stylesheet endpoint and scans configured content files for CSS classes.
UsePennington WebApplication UsePennington(this WebApplication): Package Pennington
Configure the Pennington middleware pipeline.
UsePenningtonLiveReload WebApplication UsePenningtonLiveReload(this WebApplication): Package Pennington
Adds live reload WebSocket support for development. Skipped during static build (see PenningtonBuildMode).
UsePenningtonLocaleRouting WebApplication UsePenningtonLocaleRouting(this WebApplication): Package Pennington
Adds locale detection and URL path rewriting middleware. Must be called MapRazorComponents so that Blazor routing sees the locale-stripped path (e.g., /gen-z/schedule becomes /schedule). Called automatically by UsePennington when it hasn't been called yet, but at that point it is too late for Blazor endpoint routing. Sites that use @page directives with locale prefixes must call this explicitly.

UseSpaNavigation IEndpointRouteBuilder UseSpaNavigation(this IEndpointRouteBuilder): Package Pennington
Map the SPA data endpoint.

Host runtime helpers

Entry points that dispatch between dev-serve and static-build based on args[0]. Dev and build share one rendering pipeline; the build branch calls app.StartAsync(), resolves OutputGenerationService, crawls the running host via HTTP, and writes to OutputOptions.OutputDirectory.

See RunOrBuildAsync on the PenningtonExtensions type page for the full dispatch contract.

Example

A complete DocSite host wiring all three layers — AddDocSite, UseDocSite, RunDocSiteAsync — in their canonical call order.

using Pennington.DocSite;
  
var builder = WebApplication.CreateBuilder(args);
  
// Swap the bare `AddPennington` host for the DocSite template. `AddDocSite`
// wires the full documentation experience on top of Pennington core — a
// Blazor-rendered layout with sidebar navigation, header, search surface,
// outline nav, dark-mode toggle — driven entirely from `DocSiteOptions`.
builder.Services.AddDocSite(() => new DocSiteOptions
{
    SiteTitle = "Scaffold Docs",
    Description = "A minimal DocSite scaffold showing AddDocSite and area routing.",
    GitHubUrl = "https://github.com/usepennington/pennington",
    HeaderContent = """<a href="/">Scaffold Docs</a>""",
    FooterContent = """<footer class="mt-16 py-8 text-center text-sm text-base-500">Built with Pennington DocSite.</footer>""",
  
    // Each area maps to a top-level folder under `Content/` and to a URL
    // prefix. The sidebar renders an area selector when more than one is
    // configured and only shows the TOC for the active area.
    Areas =
    [
        new ContentArea("Guides", "guides"),
        new ContentArea("Reference", "reference"),
    ],
});
  
var app = builder.Build();
  
// `UseDocSite` mounts locale routing, antiforgery, static files, Razor
// component routing (`Pages.razor` owns `/{*fileName:nonfile}`), MonorailCSS,
// SPA navigation, and the core Pennington middleware in the right order.
app.UseDocSite();
  
// `RunDocSiteAsync` delegates to `RunOrBuildAsync`, so `dotnet run` serves live
// and `dotnet run -- build <baseUrl> <outputDir>` generates static HTML. Both
// positional args are optional (defaults: `/` and `output`).
await app.RunDocSiteAsync(args);

The same three-call shape holds for every template: Add* builds the service graph, Use* mounts the middleware and endpoints, Run*Async reads args and either serves or builds.

IServiceCollection extensions

WebApplication and endpoint extensions

Host runtime helpers

Example

See also

`IServiceCollection` extensions

`WebApplication` and endpoint extensions