Docs

Remarks

Adds the RazorDocs harvesting, aggregation, and sanitization services via services.AddRazorDocs(). RazorDocs styling is compiled into the package during the RazorDocs build and the layout resolves the correct static asset path for root-module versus embedded consumer hosts, so hosts do not register services.AddTailwind() just to light up the embedded docs UI.

Remarks

This hook only mutates the pipeline when versioning is enabled and the resolved RazorDocsVersionCatalogService yields at least one available published tree. In that case the module mounts exact-version exports, optionally adds the configured route-family root alias for the recommended release, and inserts a short-circuiting middleware branch that lets RazorDocsPublishedTreeHandler serve matching requests before the live preview surface sees them.

Remarks

Public exact-version mounts always preserve the authored catalog order. When the recommended release points at a public exact tree, this helper adds the configured route-family root alias as an extra mount root that reuses the same PhysicalFileProvider instance instead of duplicating file watchers for the same export path.

Remarks

When RazorDocs is the root module assembly, standalone and static-export hosts preserve the historical /css/site.gen.css URL by redirecting it to the packaged Razor Class Library stylesheet at /_content/ForgeTrust.AppSurface.Docs/css/site.gen.css. Embedded hosts do not register that redirect because they already link to the packaged asset directly. Redirects preserve the request HttpRequest.PathBase and query string so legacy links continue to work behind a virtual path, but the path base and configured package target must remain single-slash app-relative path components.

When versioning is enabled, this hook also reserves the stable version entry route at the configured route-family root, adds the archive surface below that route root, and serves preview-surface assets from either the live web root or the packaged Razor Class Library depending on whether published-tree mounts can shadow the stable docs root. Asset routes are built with DocsUrlBuilder.BuildAssetUrl(string) for search.css, minisearch.min.js, search-client.js, and the page-local outline-client.js. Preview hosts can serve those files directly from the web root; otherwise the current-surface URLs redirect through ResolveLegacySearchAssetBasePath to the packaged RazorDocs assets. Legacy asset redirects preserve only the request query string, while the redirect path itself is constrained to an app-relative URL so cache-busting parameters cannot turn the redirect into an external hop. Route ordering matters: index, search, search-index, section, and catch-all routes are registered from most to least specific so the live preview root continues to behave correctly even when the current docs root is root-mounted or overlaps published exact-version aliases.

When RazorDocs is the root module, the bare application root redirects to the configured docs home. This keeps standalone docs hosts and static exports useful after route isolation removed the old app-wide controller fallback. Embedded hosts do not get this redirect; their owning app should decide what / means.

The operator-facing harvest health route patterns are always registered before the catch-all docs route so {DocsRootPath}/_health and {DocsRootPath}/_health.json remain reserved operator paths rather than falling through to document lookup. The route named razordocs_harvest_health maps the current docs root health pattern from DocsUrlBuilder.BuildHealthUrl to DocsController.HarvestHealth, and razordocs_harvest_health_json maps DocsUrlBuilder.BuildHealthJsonUrl to DocsController.HarvestHealthJson. The controller actions still gate responses with RazorDocsHarvestHealthVisibility.AreRoutesExposed(RazorDocsOptions, IHostEnvironment): by default they return health only in Development, while production hosts must opt in with RazorDocsHarvestHealthOptions.ExposeRoutes. These routes are intended for local and operator verification, not as unauthenticated public reader navigation.

Remarks

This helper intentionally treats query text as data appended after the validated path. It validates the unescaped path base so unsafe separators are not hidden by URI formatting, then emits the escaped path base used for redirect headers. A root path base (/) is normalized to empty so the redirect stays single-slash local. It does not allow the path base or target path to be absolute, protocol-relative, backslash-prefixed, or control-character-bearing because those shapes can be interpreted by clients as redirects away from the current host.

Remarks

During post-configuration this method rehydrates null nested option blocks with defaults, trims nullable string settings such as repository roots and contributor URL templates, normalizes RazorDocsRoutingOptions.RouteRootPath and RazorDocsRoutingOptions.DocsRootPath through DocsUrlBuilder.NormalizeRouteRootPath(string?, string, bool) and DocsUrlBuilder.NormalizeDocsRootPath(string?, bool), trims RazorDocsVersioningOptions.CatalogPath, and removes blank or duplicate sidebar namespace prefixes. Callers that omit RazorDocsOptions.Routing or RazorDocsOptions.Versioning can therefore still rely on a fully populated options object after registration. When RazorDocsHarvestOptions.FailOnFailure is enabled, the registered startup preflight fails the host only when the aggregate harvest health is failed.

When RazorDocsRoutingOptions.DocsRootPath is omitted or whitespace, the live docs root is derived from the normalized RazorDocsRoutingOptions.RouteRootPath through DocsUrlBuilder.ResolveDefaultDocsRootPath(string, bool). For example, RazorDocs:Routing:RouteRootPath=/foo/bar with versioning enabled produces /foo/bar/next as the default live root. Callers that set both RazorDocsRoutingOptions.RouteRootPath and RazorDocsRoutingOptions.DocsRootPath should keep the pair coherent so stable entry, archive, exact-version, and live preview routes compose predictably after DocsUrlBuilder.NormalizeRouteRootPath(string?, string, bool) and DocsUrlBuilder.NormalizeDocsRootPath(string?, bool) run.

The method also registers DocsUrlBuilder and RazorDocsVersionCatalogService as singleton downstream services alongside the standard harvesters, memo cache, and DocAggregator. Consumers that resolve RazorDocsOptions directly should expect the normalized values rather than raw configuration text, and applications that need custom routing or catalog paths should provide those values before this method runs so the normalized singleton graph stays consistent.