string StylesheetPath { get; }
Source
Gets the application-relative stylesheet path to use from AppSurface Docs layouts.
Docs
Namespaces
AppSurfaceDocsAssetPathResolver
SourceResolves stylesheet paths for AppSurface Docs hosts.
Remarks
When the current application's root module lives in the AppSurface Docs assembly, AppSurface Docs layouts preserve the historical root stylesheet URL at ~/css/site.gen.css. Published and exported hosts may only materialize the packaged Razor Class Library asset path, so AppSurfaceDocsWebModule also preserves the root URL via a compatibility redirect to ~/_content/ForgeTrust.AppSurface.Docs/css/site.gen.css. Root-module hosts also serve /favicon.ico from the packaged AppSurface Docs document-layers SVG mark unless a host configures an explicit SVG favicon, so browsers that request the conventional favicon URL do not produce a 404 before the linked SVG favicon is discovered. When AppSurface Docs is consumed from another host assembly, layouts link directly to that packaged asset path.
CreateDefault
AppSurfaceDocsAssetPathResolver CreateDefault()
Source
Creates the default asset-path resolver used when only the AppSurface Docs services are registered.
Returns
A resolver that assumes AppSurface Docs is embedded in another host.
CreateForRootModule
AppSurfaceDocsAssetPathResolver CreateForRootModule(Assembly rootModuleAssembly)
Source
Creates the asset-path resolver for the supplied root module assembly.
Parameters
rootModuleAssemblyThe assembly that owns the current host's root module.
Returns
The resolver that matches the current host's AppSurface Docs asset layout.
IsRootModuleAssembly
bool IsRootModuleAssembly(Assembly rootModuleAssembly)
Source
Determines whether the supplied root module assembly belongs to the AppSurface Docs standalone host.
Parameters
rootModuleAssemblyThe assembly that owns the current host's root module.
Returns
true when AppSurface Docs is the root module or when the root assembly explicitly marks itself as an AppSurface Docs root host; otherwise, false.
Remarks
The standalone executable uses a tiny root module from its own assembly so MVC can discover app-owned Razor views. The assembly metadata marker lets that executable keep the same root-host asset and redirect behavior without requiring the reusable Docs package to reference the standalone assembly.
StylesheetPath
BrandIconPath
string BrandIconPath { get; }
Source
Gets the application-relative path for the default AppSurface Docs document-layers mark static asset.
Remarks
The value resolves to PackagedBrandIconPath, the bundled static-web-assets location ~/_content/ForgeTrust.AppSurface.Docs/docs/appsurface-docs-icon.svg. AppSurface Docs also maps this URL to an embedded-resource fallback when static web asset manifests are unavailable, which keeps packaged .NET tool hosts self-contained. Razor views should use this property when referencing the AppSurface brand mark served by the docs host so the packaged asset path is maintained in one place instead of being repeated in layout markup. The returned path is application-relative; callers that render under a path base should pass it through URL helpers such as Url.Content, and hosts that rewrite assets through a CDN or a non-standard static-web-assets layout should use their explicit asset URL instead.
AppSurfaceDocsCSharpHarvestOptions
SourceC# API-reference harvest path policy settings.
Remarks
These options refine AppSurfaceDocsHarvestOptions.Paths for C# source candidates. Source-specific includes compose with global includes using AND semantics, and source-specific excludes win over includes and default-exclusion allows. The built-in C# harvester also has a C#-only default group that excludes example application source while still allowing public example README files to be harvested by Markdown.
IncludeGlobs
string[] IncludeGlobs { get; set; }
Source
Gets or sets C#-specific include globs.
ExcludeGlobs
string[] ExcludeGlobs { get; set; }
Source
Gets or sets C#-specific exclude globs.
DefaultExclusions
AppSurfaceDocsHarvestDefaultExclusionOptions DefaultExclusions { get; set; }
Source
Gets or sets C#-specific default-exclusion group controls.
MaxFileSizeBytes
long MaxFileSizeBytes { get; set; }
Source
Gets or sets the largest C# file, in bytes, that the harvester will read and parse.
Remarks
Oversized files are skipped with a harvest diagnostic before Roslyn parsing so generated or adversarial source cannot dominate harvest memory. Prefer excluding generated source with ExcludeGlobs instead of raising this limit. The value must be greater than zero; zero and negative values are invalid and are rejected during options validation. The DefaultMaxFileSizeBytes default is sized for authored API source, not as a Roslyn parser safety threshold.
AppSurfaceDocsVersionCatalog
SourceDeclares the published AppSurface Docs versions that should be exposed through the version archive and static-tree mounting.
Remarks
The catalog is the release-level source of truth for version routing and archive presentation. It does not describe individual documentation pages; instead it points at already-exported exact-version trees and records release state such as support posture, visibility, and advisory severity. The runtime validates each published tree independently so one broken version does not take down the whole docs host.
RecommendedVersion
string? RecommendedVersion { get; set; }
Source
Gets or sets the exact version that should also be exposed through the configured route-family root alias.
Versions
List<AppSurfaceDocsPublishedVersion> Versions { get; set; }
Source
Gets or sets the published versions known to the catalog.
AppSurfaceDocsPublishedVersion
SourceDescribes one published AppSurface Docs release tree.
Version
string Version { get; set; }
Source
Gets or sets the exact published version identifier, such as 0.4.0 or 1.2.3-rc.1.
Label
string? Label { get; set; }
Source
Gets or sets the short reader-facing label for the release.
Summary
string? Summary { get; set; }
Source
Gets or sets optional summary copy shown in the version archive.
ExactTreePath
string? ExactTreePath { get; set; }
Source
Gets or sets the trusted-release-root-relative path to the exported exact-version docs subtree.
Remarks
The directory should contain the static files exported from the stable docs surface for one exact release, such as index.html, search-index.json, section routes, and detail pages. AppSurface Docs can then mount that same artifact at either RouteRootPath or {RouteRootPath}/v/{version} by rebasing stable-root links at response time. Relative paths resolve from AppSurfaceDocsVersioningOptions.TrustedReleaseRootPath. When that option is blank, the trusted release root defaults to the directory containing the version catalog file. Values such as ./releases/1.2.3 are valid after normalization, but rooted paths and paths containing .. are unavailable and are never mounted.
ReleaseManifestSha256
string? ReleaseManifestSha256 { get; set; }
Source
Gets or sets the SHA-256 digest of the release archive manifest that this catalog entry expects.
Remarks
The value pins the bytes of .appsurface-docs-release-manifest.json in trusted host configuration. AppSurface Docs verifies the manifest, required handler-servable file coverage, and every covered file before mounting the exact tree. Public catalog entries without this pin are unavailable because mounted archive HTML, scripts, stylesheets, SVG, and search payloads must be proven against a catalog trust anchor.
SupportState
AppSurfaceDocsVersionSupportState SupportState { get; set; }
Source
Gets or sets the support-state badge surfaced in the version archive.
Visibility
AppSurfaceDocsVersionVisibility Visibility { get; set; }
Source
Gets or sets the archive visibility behavior for the release.
AdvisoryState
AppSurfaceDocsVersionAdvisoryState AdvisoryState { get; set; }
Source
Gets or sets the release-level advisory state surfaced beside the version.
AppSurfaceDocsVersionSupportState
SourceDescribes the support posture for one published docs release.
Remarks
Numeric values are explicit and stable because catalog payloads and downstream consumers may serialize or persist these states outside the current process.
AppSurfaceDocsVersionVisibility
SourceControls whether a published version appears in the public archive and is mounted for static serving.
Remarks
Numeric values are explicit and stable because catalog payloads and downstream consumers may serialize or persist these states outside the current process.
AppSurfaceDocsVersionAdvisoryState
SourceDescribes release-level advisory severity shown in the archive.
Remarks
Numeric values are explicit and stable because catalog payloads and downstream consumers may serialize or persist these states outside the current process.
AppSurfaceDocsWebModule
SourceWeb module configuration for the AppSurface Docs documentation system.
Remarks
This module owns both the live source-backed AppSurface Docs surface and the optional published-version overlay used when AppSurfaceDocsVersioningOptions.Enabled is turned on. Service registration wires up harvesting, aggregation, sanitization, URL generation, and version-catalog resolution through services.AddAppSurfaceDocs(), while endpoint and middleware hooks decide whether the host behaves like a plain live docs site or a mixed live-plus-archive experience.
ConfigureServices
void ConfigureServices(StartupContext context, IServiceCollection services)
Source
Registers services required by the AppSurface Docs module into the provided service collection.
Remarks
Adds the AppSurface Docs harvesting, aggregation, and sanitization services via services.AddAppSurfaceDocs(). AppSurface Docs styling is compiled into the package during the AppSurface Docs 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.
RegisterDependentModules
void RegisterDependentModules(ModuleDependencyBuilder builder)
Source
Registers runtime module dependencies for this web module, including RazorWireWebModule.
Parameters
builderThe dependency builder used to register required modules.
ConfigureHostBeforeServices
void ConfigureHostBeforeServices(StartupContext context, IHostBuilder builder)
Source
Performs host-level configuration steps before application services are registered.
Parameters
contextThe startup context providing module and environment information.builderThe host builder to configure prior to service registration.
ConfigureHostAfterServices
void ConfigureHostAfterServices(StartupContext context, IHostBuilder builder)
Source
Performs host-level configuration steps after application services have been registered.
Parameters
contextThe startup context providing module and environment information.builderThe host builder to modify or extend after services are configured.
ConfigureWebApplication
void ConfigureWebApplication(StartupContext context, IApplicationBuilder app)
Source
Configures the application's request pipeline and middleware for this module.
Parameters
contextThe startup context for the module invocation.appThe application builder used to configure middleware and endpoints.
Remarks
This hook only mutates the pipeline when versioning is enabled and the resolved AppSurfaceDocsVersionCatalogService 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 AppSurfaceDocsPublishedTreeHandler serve matching requests before the live preview surface sees them.
BuildPublishedTreeMounts
(IReadOnlyList<AppSurfaceDocsPublishedTreeMount> Mounts, IReadOnlyList<PhysicalFileProvider> Providers) BuildPublishedTreeMounts(AppSurfaceDocsResolvedVersionCatalog catalog, DocsUrlBuilder docsUrlBuilder)
Source
Builds the published-tree mount table for the current resolved version catalog.
Parameters
catalogThe resolved version catalog that describes available published trees.docsUrlBuilderThe configured URL builder that supplies the route-family alias root.
Returns
The ordered mount list plus the unique provider instances that should be disposed with the host lifetime.
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. Frozen route manifest caches follow the same reuse rule: exact tree paths are resolved to full paths, trimmed of trailing directory separators, and compared with the platform-aware physical path comparer so canonical and recommended mounts that point at the same tree share one AppSurfaceDocsFrozenRouteManifestCache when they have the same verification model. If a later mount for the same tree has a verified release archive and the existing cache is still an unverified lazy filesystem cache, the helper replaces that cache entry with a verified snapshot built from AppSurfaceDocsVerifiedReleaseArchive.FrozenRouteManifest. Consumers should treat the returned cache instances as immutable mount dependencies: recommended aliases and public version mounts observe the verified snapshot when one exists, otherwise they share the same lazy filesystem-backed read model.
ConfigureEndpoints
void ConfigureEndpoints(StartupContext context, IEndpointRouteBuilder endpoints)
Source
Adds the module's default controller routes and supporting asset routes for documentation endpoints.
Parameters
contextStartup context for the application and environment.endpointsEndpoint route builder used to map the module's routes.
Remarks
When AppSurface Docs 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. The packaged AppSurface brand icon is also served from an embedded fallback so static exports that disable static-web-assets can still validate the layout image. Consumer-owned branding assets can be served from a configured filesystem directory, including directories outside AppSurface Docs packaged static web assets, under a dedicated request prefix. Preview hosts can serve those files directly from the web root; otherwise the current-surface URLs redirect through ResolveLegacySearchAssetBasePath to the packaged AppSurface Docs 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 AppSurface Docs is the root module, the bare application root redirects to the configured docs home and /favicon.ico serves the packaged AppSurface Docs document-layers SVG mark unless the host configures AppSurfaceDocsFaviconOptions.SvgPath. In that case /favicon.ico redirects to the configured SVG path so standalone docs hosts can keep the conventional browser favicon probe aligned with rendered <link rel="icon"> metadata. Embedded hosts do not get these root routes; their owning app should decide what / and /favicon.ico mean.
The operator-facing diagnostics route patterns are always registered before the catch-all docs route so {DocsRootPath}/_harvest, {DocsRootPath}/_harvest/rebuild, {DocsRootPath}/_health, {DocsRootPath}/_health.json, {DocsRootPath}/_routes, and {DocsRootPath}/_routes.json remain reserved operator paths rather than falling through to document lookup. The route named appsurfacedocs_harvest maps the current docs root harvest observatory pattern from DocsUrlBuilder.BuildHarvestUrl to DocsController.Harvest. The route named appsurfacedocs_harvest_rebuild maps DocsUrlBuilder.BuildHarvestRebuildUrl to DocsController.RebuildHarvest. The route named appsurfacedocs_harvest_health maps the current docs root health pattern from DocsUrlBuilder.BuildHealthUrl to DocsController.HarvestHealth, and appsurfacedocs_harvest_health_json maps DocsUrlBuilder.BuildHealthJsonUrl to DocsController.HarvestHealthJson. Route inspector routes map DocsUrlBuilder.BuildRouteInspectorUrl and DocsUrlBuilder.BuildRouteInspectorJsonUrl to DocsController.RouteInspector and DocsController.RouteInspectorJson. The controller actions still gate responses with their exposure options: harvest health uses AppSurfaceDocsHarvestHealthVisibility.AreRoutesExposed(AppSurfaceDocsOptions, IHostEnvironment): by default they return health only in Development, while production hosts must opt in with AppSurfaceDocsHarvestHealthOptions.ExposeRoutes; route inspector uses AppSurfaceDocsDiagnosticsOptions.ExposeRouteInspector. These routes are intended for local and operator verification, not as unauthenticated public reader navigation.
The route named appsurfacedocs_search_index_refresh maps the pattern produced by DocsUrlBuilder.BuildSearchIndexRefreshUrl to DocsController.RefreshSearchIndex. That operator route is browser-form-shaped and accepts only POST; the companion unsupported-method endpoint rejects common non-POST verbs with HTTP 405 and an Allow: POST response header instead of letting the request fall through to reader document lookup or status-code-page rendering.
ResolveHealthAuthorizationPolicyName
string? ResolveHealthAuthorizationPolicyName(AppSurfaceDocsOptions docsOptions, IServiceProvider services)
Source
Resolves the effective health-route authorization policy name, or null when no policy should be applied.
Remarks
Returns null when no health or shared read policy should be applied, when no IWebHostEnvironment is available, or when the health routes are not exposed for the current environment. ApplyHealthAuthorizationPolicy depends on this ordering so hidden health routes keep returning 404 before authorization metadata is added. The legacy health policy takes precedence when it is configured; otherwise the shared diagnostics read policy protects exposed health routes.
BuildLegacyAssetRedirectPath
string BuildLegacyAssetRedirectPath(PathString pathBase, string targetPath, QueryString queryString)
Source
Builds the local redirect target used when historical docs asset URLs move to packaged Razor Class Library assets.
Parameters
pathBaseThe current request path base to preserve for applications mounted below a prefix.targetPathThe package asset path selected by AppSurface Docs endpoint configuration.queryStringThe request query string to preserve for cache-busting or diagnostics parameters.
Returns
An escaped, single-slash app-relative redirect target with the original query string appended.
Exceptions
InvalidOperationExceptionThrown whenpathBaseortargetPathis not a safe app-relative path component.
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.
ResolveBrandingAssetsDirectoryPath
string? ResolveBrandingAssetsDirectoryPath(IServiceProvider services, AppSurfaceDocsOptions options)
Source
Resolves the configured branding asset directory against the repository root or content root.
ResolveBrandingAssetsRequestPath
string? ResolveBrandingAssetsRequestPath(AppSurfaceDocsOptions options)
Source
Resolves the browser route prefix used for configured branding assets.
TryResolveSafeBrandingAssetPath
bool TryResolveSafeBrandingAssetPath(object? routeValue, bool allowSvgAssets, out string assetPath)
Source
Resolves a route-captured branding asset path only when it stays relative and points at an allowed image asset.
Parameters
routeValueThe route-captured asset path to validate and decode.allowSvgAssetstrueto allow.svgfiles for a trusted branding directory; otherwise SVG files are denied by default and only bitmap/icon extensions are accepted.assetPathThe decoded relative asset path when validation succeeds, or an empty string when validation fails.
Remarks
This method accepts only relative browser paths that decode cleanly, do not contain rooted paths, backslashes, control characters, or traversal segments, and end with an allowed branding image extension. It rejects .svg unless allowSvgAssets is true.
Callers should pass the raw route value before filesystem joining or other path normalization. Do not pass already-normalized absolute paths, rely on the filename alone, or treat a successful result as content-level sanitization. Enabling SVG serving expands the attack surface because SVG is active document content; this helper only enforces path and extension safety and does not optimize or sanitize SVG bytes.
ResolveConfiguredRootFaviconRedirectPath
string? ResolveConfiguredRootFaviconRedirectPath(AppSurfaceDocsOptions options)
Source
Resolves the standalone root favicon redirect target for a configured SVG favicon.
AppSurfaceDocsOptions
SourceRepresents configuration for the AppSurface Docs package and host.
Mode
AppSurfaceDocsMode Mode { get; set; }
Source
Gets or sets the active docs source mode.
CacheExpirationMinutes
double CacheExpirationMinutes { get; set; }
Source
Gets or sets the absolute docs snapshot cache lifetime in minutes. The default is DefaultCacheExpirationMinutes minutes.
Remarks
This setting controls the shared aggregation snapshot used by docs pages, public-section data, and the generated search-index payload. Shorter values make source-backed development changes visible sooner, while longer values reduce repeated harvest and search-index generation work in production hosts. The value must be finite, must be between MinCacheExpirationMinutes and MaxCacheExpirationMinutes, and must represent a whole number of seconds because the generated search-index Cache-Control max-age header uses whole-second delta values. Values outside those constraints are rejected during options validation.
Identity
AppSurfaceDocsIdentityOptions Identity { get; set; }
Source
Gets identity settings used by the built-in docs chrome.
Theme
AppSurfaceDocsThemeOptions Theme { get; set; }
Source
Gets theme and layout settings used by the built-in docs chrome.
Remarks
Theme settings are the supported customization contract for AppSurface Docs visual branding. They intentionally expose presets, accent/link roles, density, and chrome compactness instead of the full internal --docs-* CSS variable layer. Leave these settings unset to use the default AppSurface dark theme.
Source
AppSurfaceDocsSourceOptions Source { get; set; }
Source
Gets source-mode settings used when docs are harvested from a repository checkout.
Harvest
AppSurfaceDocsHarvestOptions Harvest { get; set; }
Source
Gets harvest policy settings used by runtime and export hosts.
Diagnostics
AppSurfaceDocsDiagnosticsOptions Diagnostics { get; set; }
Source
Gets diagnostics settings for maintainer-facing AppSurface Docs inspection surfaces.
Metrics
AppSurfaceDocsMetricsOptions Metrics { get; set; }
Source
Gets search-quality metrics settings for AppSurface Docs.
Remarks
Metrics are disabled by default. Enabling this block controls only AppSurface Docs search-quality events and does not enable unrelated AppSurface or RazorWire experimental product-intelligence contracts. Use the browser collector for static exports and live hosted docs that should forward safe registry-shaped events to a configured endpoint. Use hosted collection and hosted review when a running AppSurface Docs server should validate browser submissions, forward accepted events to host-owned sinks, and expose a bounded maintainer diagnostics surface.
Bundle
AppSurfaceDocsBundleOptions Bundle { get; set; }
Source
Gets bundle-mode settings used by future bundle-backed runtime loading.
Sidebar
AppSurfaceDocsSidebarOptions Sidebar { get; set; }
Source
Gets sidebar rendering settings.
Contributor
AppSurfaceDocsContributorOptions Contributor { get; set; }
Source
Gets contributor provenance settings used to render source, edit, and freshness evidence on details pages.
Routing
AppSurfaceDocsRoutingOptions Routing { get; set; }
Source
Gets routing settings that control where the live AppSurface Docs source surface is exposed.
Versioning
AppSurfaceDocsVersioningOptions Versioning { get; set; }
Source
Gets versioning settings used to mount exact release trees and the archive surface.
Localization
AppSurfaceDocsLocalizationOptions Localization { get; set; }
Source
Gets localization settings for locale-aware live docs routes, metadata, search projections, and fallback policy.
Remarks
Localization is disabled by default so existing AppSurface Docs hosts keep their current routes, search payload shape, and view behavior until they opt in. When enabled, this object defines the supported locales, the default locale, route-prefix behavior, fallback policy, and search scoping defaults used by the locale-aware document graph.
AppSurfaceDocsThemeOptions
SourceTheme configuration for AppSurface Docs browser chrome and package-owned docs surfaces.
Remarks
Use this object when a consuming repository needs branded docs without replacing Razor views or depending on internal CSS selectors. AppSurface Docs resolves these settings into a package-owned CSS variable set at render time so live docs, search, static export, and published archives share the same visual contract.
Preset
AppSurfaceDocsThemePreset Preset { get; set; }
Source
Gets or sets the preset palette used before applying supported color overrides.
Remarks
The default is AppSurfaceDocsThemePreset.AppSurfaceDark. V1 presets are dark-only so code highlighting, search states, and existing docs chrome keep their contrast guarantees.
Colors
AppSurfaceDocsThemeColorOptions Colors { get; set; }
Source
Gets color role overrides for the selected preset.
Layout
AppSurfaceDocsThemeLayoutOptions Layout { get; set; }
Source
Gets layout density and chrome compactness settings for package-owned docs UI.
AppSurfaceDocsThemeColorOptions
SourceSupported color-role overrides for AppSurface Docs themes.
Remarks
Values must be CSS hex colors such as #14b8a6 or #93c5fd. Blank values use the selected preset default. These roles are intentionally narrow: surface, text, border, syntax, and semantic-status colors remain preset-owned in v1 so maintainers do not inherit a large CSS-token compatibility burden.
AccentColor
string? AccentColor { get; set; }
Source
Gets or sets the primary accent color used by links, active states, highlights, and related affordances.
AccentStrongColor
string? AccentStrongColor { get; set; }
Source
Gets or sets the stronger accent color used by focus rings, selected-state fills, and high-emphasis borders.
LinkColor
string? LinkColor { get; set; }
Source
Gets or sets the standard prose and chrome link color.
VisitedLinkColor
string? VisitedLinkColor { get; set; }
Source
Gets or sets the visited prose link color.
AppSurfaceDocsThemeLayoutOptions
SourceLayout controls for package-owned AppSurface Docs chrome.
Density
AppSurfaceDocsThemeDensity Density { get; set; }
Source
Gets or sets the repeated-chrome density.
Remarks
Compact density reduces repeated sidebar, metadata, search-result, and adjacent chrome spacing. It does not reduce Markdown prose line height or mobile touch-target floors.
Chrome
AppSurfaceDocsThemeChrome Chrome { get; set; }
Source
Gets or sets the amount of brand, sidebar, and header chrome.
Remarks
Compact chrome shortens package-owned shell spacing while preserving search visibility, keyboard order, and mobile navigation hierarchy.
AppSurfaceDocsIdentityOptions
SourceIdentity configuration for AppSurface Docs browser chrome.
Remarks
Identity settings intentionally cover the low-level brand assets every consuming repository expects to own: display name, logo, favicon variants, optional branding-asset directory serving, and the brand home link. Theme, layout, color, typography, and template customization stay separate so identity remains safe to configure from appsettings, config_*.json, command-line arguments, and environment variables.
DisplayName
string? DisplayName { get; set; }
Source
Gets or sets the visible product name rendered in titles and navigation chrome.
Remarks
Blank values fall back to DefaultDisplayName. The value is plain text and is HTML-encoded by Razor views; do not put markup here.
HomeHref
string? HomeHref { get; set; }
Source
Gets or sets the brand link target used by the built-in docs chrome.
Remarks
When omitted or blank, AppSurface Docs links the brand to the configured docs home route. Configured values must be app-root browser paths such as /docs or application-relative paths such as ~/docs. Remote URLs, relative paths, query strings, fragments, and protocol-relative URLs are rejected during startup validation.
Logo
AppSurfaceDocsLogoOptions Logo { get; set; }
Source
Gets logo settings used by the built-in navigation chrome.
Wordmark
AppSurfaceDocsWordmarkOptions Wordmark { get; set; }
Source
Gets wordmark presentation settings used by the built-in navigation chrome.
Favicon
AppSurfaceDocsFaviconOptions Favicon { get; set; }
Source
Gets favicon settings emitted into the document head.
BrandingAssets
AppSurfaceDocsBrandingAssetsOptions BrandingAssets { get; set; }
Source
Gets optional static-file serving settings for consumer-owned branding assets.
AppSurfaceDocsBrandingAssetsOptions
SourceStatic-file serving settings for consumer-owned AppSurface Docs branding assets.
Remarks
These settings bridge the difference between filesystem asset ownership and browser paths. DirectoryPath points at a directory on disk that can live outside AppSurface Docs packaged static web assets, while RequestPath defines the app-root browser prefix used by AppSurfaceDocsLogoOptions.Path and AppSurfaceDocsFaviconOptions paths.
Logo and favicon paths are browser URL paths, not filesystem paths, and are not joined with DirectoryPath. When DirectoryPath is branding and RequestPath uses its default /branding, a file at branding/logo.png is referenced as /branding/logo.png. SVG files use the same URL mapping only after AllowSvgAssets is enabled for a trusted branding directory.
Relative directory paths resolve against AppSurfaceDocsSourceOptions.RepositoryRoot when configured; otherwise they resolve against the host content root. Absolute directory paths are served as-is. The endpoint only serves common web image and icon file extensions; keep this directory dedicated to public brand assets. SVG files are denied by default because SVG is active document content; enable AllowSvgAssets only for operator-owned assets that are already trusted. Leave DirectoryPath blank when the owning application serves branding assets itself.
DirectoryPath
string? DirectoryPath { get; set; }
Source
Gets or sets the filesystem directory containing consumer-owned branding assets.
Remarks
Values may be absolute paths, repository-relative paths when AppSurfaceDocsSourceOptions.RepositoryRoot is configured, or content-root-relative paths otherwise. The directory is not enabled until this value is non-blank. This is a server-side filesystem path; logo and favicon options still use browser paths under RequestPath. The serving endpoint intentionally ignores files outside the supported image and icon extension set.
RequestPath
string? RequestPath { get; set; }
Source
Gets or sets the app-root or application-relative URL prefix used to serve DirectoryPath.
Remarks
Defaults to /branding. Values must follow the same browser-path rules as logo and favicon paths and must not be the application root because branding asset serving is intentionally scoped to a dedicated path prefix. Override this only when /branding conflicts with an owning application route.
AllowSvgAssets
bool AllowSvgAssets { get; set; }
Source
Gets or sets a value indicating whether AppSurface Docs may serve SVG files from DirectoryPath.
Remarks
The default is false. SVG is an active document format, not only an optimized image format, and standard SVG optimization does not make arbitrary SVG safe to serve under the application origin. Enable this only for branding directories whose SVG files are owned and reviewed by trusted operators. Hosts that need SVG sanitization should perform that sanitization before files reach the configured branding directory.
AppSurfaceDocsWordmarkOptions
SourceWordmark presentation settings for AppSurface Docs browser chrome.
Remarks
Wordmark settings are intentionally opt-in so the built-in docs chrome stays short, bounded, and plain text by default. Use them when the publishing repository needs a specific product wordmark, shorter display treatment, or substring highlight color. The highlighted text must appear in the resolved display name, and the color accepts only CSS hex values so configuration cannot inject arbitrary style declarations into the package layout.
HighlightText
string? HighlightText { get; set; }
Source
Gets or sets the display-name substring highlighted by the built-in docs chrome.
Remarks
Blank values disable wordmark highlighting. Non-blank values must match part of the resolved AppSurfaceDocsIdentityOptions.DisplayName using ordinal comparison. Only the first occurrence is highlighted; choose a more specific substring if the display name repeats the same word.
HighlightColor
string? HighlightColor { get; set; }
Source
Gets or sets the CSS hex color used for the highlighted wordmark substring.
Remarks
Valid values are CSS hex colors such as #3b82f6 or #38bdf8. Blank values leave the highlighted substring in the surrounding text color. Supplying a color without HighlightText is rejected because it has no visible effect.
AppSurfaceDocsLogoOptions
SourceLogo settings for AppSurface Docs browser chrome.
Path
string? Path { get; set; }
Source
Gets or sets the app-root or application-relative logo path.
Remarks
Valid values look like /branding/docs-logo.svg or ~/branding/docs-logo.svg. This is always a browser URL path. When AppSurfaceDocsBrandingAssetsOptions.DirectoryPath is configured, reference files through the branding request prefix, for example /branding/docs-logo.svg for branding/docs-logo.svg. Remote URLs, relative paths, query strings, fragments, backslashes, and traversal segments are rejected.
AltText
string? AltText { get; set; }
Source
Gets or sets accessible text for logo-only renderers that consume the resolved identity.
Remarks
When omitted or blank, the resolved display name is used. The built-in AppSurface Docs chrome renders configured logo images as decorative because the visible display name is rendered in the same brand link.
AppSurfaceDocsFaviconOptions
SourceFavicon settings for AppSurface Docs.
Remarks
When no custom favicon path is configured, the built-in layout links the packaged AppSurface Docs document-layers SVG mark. Standalone AppSurface Docs hosts also serve that same SVG mark at /favicon.ico for browsers that request the conventional root favicon URL before reading page metadata. When SvgPath is configured, standalone hosts redirect /favicon.ico to that SVG path so the conventional probe matches the rendered metadata. Embedded hosts do not claim /favicon.ico; their owning app should serve any app-wide favicon itself.
SvgPath
string? SvgPath { get; set; }
Source
Gets or sets an SVG favicon path. Values must be browser-safe app-root paths, such as /docs/favicon.svg, or application-relative paths, such as ~/docs/favicon.svg.
Remarks
Remote URLs, protocol-relative URLs, query strings, fragments, backslashes, and traversal segments are rejected during options validation. Null or blank values omit the custom SVG favicon; the layout renders the built-in AppSurface Docs SVG favicon only when no custom favicon path is configured.
IcoPath
string? IcoPath { get; set; }
Source
Gets or sets an ICO favicon path. Values must be browser-safe app-root paths, such as /favicon.ico, or application-relative paths, such as ~/favicon.ico.
Remarks
Remote URLs, protocol-relative URLs, query strings, fragments, backslashes, and traversal segments are rejected during options validation. Null or blank values omit the custom ICO favicon; the layout renders the built-in AppSurface Docs SVG favicon only when no custom favicon path is configured.
PngPath
string? PngPath { get; set; }
Source
Gets or sets a PNG favicon path. Values must be browser-safe app-root paths, such as /docs/favicon.png, or application-relative paths, such as ~/docs/favicon.png.
Remarks
Remote URLs, protocol-relative URLs, query strings, fragments, backslashes, and traversal segments are rejected during options validation. Null or blank values omit the custom PNG favicon; the layout renders the built-in AppSurface Docs SVG favicon only when no custom favicon path is configured.
AppSurfaceDocsSourceOptions
SourceSource-mode configuration for AppSurface Docs.
RepositoryRoot
string? RepositoryRoot { get; set; }
Source
Gets or sets the repository root used for source harvesting. When null, AppSurface Docs falls back to repository discovery from the content root.
AppSurfaceDocsHarvestOptions
SourceHarvest policy settings for AppSurface Docs source-backed documentation.
Remarks
The default policy is tolerant so public runtime hosts can continue serving even when source harvesting has a transient problem. Enable FailOnFailure in CI or export hosts that should fail closed when every active harvester fails, times out, or cancels. Use Paths, Markdown, and CSharp to define the repository-relative public documentation boundary shared by runtime hosts, export flows, and hygiene checks. JavaScript discovery is enabled by default and remains annotation-first; use JavaScript for JavaScript opt-out, narrowing, and strict-health behavior.
FailOnFailure
bool FailOnFailure { get; set; }
Source
Gets or sets a value indicating whether host startup should fail when the aggregate harvest health is ForgeTrust.AppSurface.Docs.Models.DocHarvestHealthStatus.Failed.
Remarks
Strict mode treats only the aggregate failed state as fatal. Empty docs and degraded partial harvests remain non-fatal in this slice because they can represent intentional empty repositories or still-usable partial docs.
StartupMode
AppSurfaceDocsHarvestStartupMode StartupMode { get; set; }
Source
Gets or sets how AppSurface Docs starts the initial source harvest.
Remarks
The default is AppSurfaceDocsHarvestStartupMode.Background, which starts the same memoized harvest during host startup and lets first requests render live progress if the snapshot is not ready within InitialRequestWaitBudgetMilliseconds. FailOnFailure still makes startup wait for the snapshot and fail closed when the aggregate status is failed.
InitialRequestWaitBudgetMilliseconds
int InitialRequestWaitBudgetMilliseconds { get; set; }
Source
Gets or sets the first-request wait budget, in milliseconds, before AppSurface Docs renders the harvest observatory.
Remarks
The budget applies only while the initial harvest is still running. Caller cancellation cancels the wait, not the shared memoized harvest. Use zero to render the observatory immediately for cold requests.
TestingPreHarvestDelayMilliseconds
int TestingPreHarvestDelayMilliseconds { get; set; }
Source
Gets or sets an artificial delay before active harvesters start, in milliseconds, for local and automated observatory testing.
Remarks
The delay is inserted after AppSurface Docs publishes the live harvest run and before it invokes any active harvester. The default is zero. This option exists so development and test hosts can intentionally keep the harvest observatory in its startup phase; do not enable it in production traffic.
TestingDelayPerHarvesterMilliseconds
int TestingDelayPerHarvesterMilliseconds { get; set; }
Source
Gets or sets an artificial delay per harvester, in milliseconds, for local and automated observatory testing.
Remarks
The delay is inserted after a harvester publishes its running state and before that harvester starts real work. The default is zero. This option exists so development and test hosts can intentionally keep the harvest observatory visible; do not enable it in production traffic.
TestingDelayPerDocumentMilliseconds
int TestingDelayPerDocumentMilliseconds { get; set; }
Source
Gets or sets an artificial delay per harvested document, in milliseconds, for local and automated observatory testing.
Remarks
The delay is inserted after a harvester returns documents and before AppSurface Docs marks that harvester complete. When live progress is available, the harvester's document count is published one document at a time. The default is zero. This option exists so development and test hosts can intentionally keep the harvest observatory visible; do not enable it in production traffic.
Health
AppSurfaceDocsHarvestHealthOptions Health { get; set; }
Source
Gets health-surface settings for the operator-facing AppSurface Docs harvest health routes and sidebar chrome.
Paths
AppSurfaceDocsHarvestPathOptions Paths { get; set; }
Source
Gets global repository-relative path policy settings shared by every built-in harvester.
Remarks
Global include globs are a repository-wide boundary. When configured, every built-in source kind must match one global include before harvester-specific includes are considered. Global excludes win over includes and default-exclusion allows.
Markdown
AppSurfaceDocsMarkdownHarvestOptions Markdown { get; set; }
Source
Gets Markdown-specific path policy settings that refine the global path policy.
CSharp
AppSurfaceDocsCSharpHarvestOptions CSharp { get; set; }
Source
Gets C# API-reference path policy settings that refine the global path policy.
JavaScript
AppSurfaceDocsJavaScriptHarvestOptions JavaScript { get; set; }
Source
Gets JavaScript public API path policy and parser settings.
AppSurfaceDocsHarvestHealthOptions
SourceOperator-facing harvest health settings for AppSurface Docs.
Remarks
The health surface exposes the same cached harvest state returned by ForgeTrust.AppSurface.Docs.Services.DocAggregator.GetHarvestHealthAsync(System.Threading.CancellationToken). Development hosts show the route response and sidebar chrome by default so local failures are visible immediately. Other environments must opt in explicitly before AppSurface Docs returns health responses or displays sidebar chrome.
AuthorizationPolicy
string? AuthorizationPolicy { get; set; }
Source
Gets or sets the host-owned authorization policy required before AppSurface Docs returns health responses from {DocsRootPath}/_health and {DocsRootPath}/_health.json.
Remarks
The default is null, which preserves the existing route-exposure behavior without adding authorization metadata. Set this to the name of an ASP.NET Core authorization policy registered by the host when exposed health routes should require authenticated maintainer access. AppSurface Docs does not register authentication schemes, identities, cookies, or fallback policies for this option; hosts must register normal ASP.NET Core authentication and authorization middleware before endpoint execution.
ExposeRoutes
AppSurfaceDocsHarvestHealthExposure ExposeRoutes { get; set; }
Source
Gets or sets when AppSurface Docs should return health responses from {DocsRootPath}/_health and {DocsRootPath}/_health.json.
Remarks
The default is AppSurfaceDocsHarvestHealthExposure.DevelopmentOnly. AppSurface Docs always reserves these route patterns ahead of the docs catch-all route so they do not fall through to document lookup. Setting this to AppSurfaceDocsHarvestHealthExposure.Always allows the controller actions to return operator-facing responses in non-development hosts; protect those responses with host-owned authentication, authorization, or network controls when they are reachable by untrusted users.
ShowChrome
AppSurfaceDocsHarvestHealthExposure ShowChrome { get; set; }
Source
Gets or sets when AppSurface Docs should show the harvest health entry in the built-in docs sidebar.
Remarks
This option is intentionally independent from ExposeRoutes so hosts can expose a machine-readable endpoint without advertising it in the docs chrome, or show local-development chrome without changing non-development route behavior.
AppSurfaceDocsDiagnosticsOptions
SourceMaintainer diagnostics settings for AppSurface Docs.
Remarks
Diagnostics surfaces expose route and harvest state intended for local development and trusted operators. The defaults keep route-inspector responses and sidebar discovery available in Development only. Setting ExposeRouteInspector or ShowChrome to AppSurfaceDocsHarvestHealthExposure.Always exposes the route only; production hosts should also set AppSurfaceDocsDiagnosticsOptions.OperatorReadPolicy unless access is enforced by the host application, reverse proxy, or network layer.
ExposeRouteInspector
AppSurfaceDocsHarvestHealthExposure ExposeRouteInspector { get; set; }
Source
Gets or sets when AppSurface Docs should return route-inspector responses from {DocsRootPath}/_routes and {DocsRootPath}/_routes.json.
ShowChrome
AppSurfaceDocsHarvestHealthExposure ShowChrome { get; set; }
Source
Gets or sets when AppSurface Docs should show route-inspector discovery in the built-in docs sidebar diagnostics chrome.
Remarks
This option is intentionally independent from ExposeRouteInspector so hosts can expose route inspector responses for trusted automation without advertising them in docs chrome, or show diagnostics chrome only in environments where maintainers are expected to use the sidebar. Chrome never creates or authorizes a route; route exposure still follows ExposeRouteInspector.
OperatorReadPolicy
string? OperatorReadPolicy { get; set; }
Source
Gets or sets the host-owned authorization policy required for exposed AppSurface Docs diagnostics read surfaces.
Remarks
The default is null, which preserves the existing route-exposure behavior without adding authorization metadata. Set this to the name of an ASP.NET Core authorization policy registered by the host when trusted operators should read diagnostics from {DocsRootPath}/_harvest, {DocsRootPath}/_routes, {DocsRootPath}/_routes.json, or the AppSurface Docs harvest progress stream. The policy also protects {DocsRootPath}/_health and {DocsRootPath}/_health.json when AppSurfaceDocsHarvestHealthOptions.AuthorizationPolicy is not configured. It does not authorize packaged operator writes, hosted metrics collection, public docs pages, static assets, or exported artifacts.
OperatorWritePolicy
string? OperatorWritePolicy { get; set; }
Source
Gets or sets the host-owned authorization policy required for mutating AppSurface Docs operator actions.
Remarks
The default is null, which denies packaged operator writes such as {DocsRootPath}/_harvest/rebuild. Set this to the name of a policy registered with ASP.NET Core authorization when trusted maintainers may rebuild the live source-backed docs harvest from browser forms or host automation. When this option is blank, AppSurface Docs falls back to SearchIndexRefreshPolicy for source compatibility with hosts that already configured the older search-index refresh endpoint.
SearchIndexRefreshPolicy
string? SearchIndexRefreshPolicy { get; set; }
Source
Gets or sets the host-owned authorization policy required to refresh the live docs search-index cache.
Remarks
The default is null, which denies the packaged {DocsRootPath}/_search-index/refresh endpoint. Set this to the name of a policy registered with ASP.NET Core authorization when a host wants browser-form-based operator refresh. New hosts should prefer OperatorWritePolicy so one docs-maintainer policy covers harvest rebuild and search refresh. AppSurface Docs does not register a permissive fallback policy because cache refresh is a mutating operator action.
AppSurfaceDocsMetricsOptions
SourceSearch-quality metrics settings for AppSurface Docs.
Remarks
This options block is intentionally docs-specific. It never captures raw search text, full URLs, reader identity, cookies, request bodies, or free-form comments. The browser collector forwards only the semantic event name and low-cardinality string properties already emitted by AppSurface Docs search UI. Hosted collection revalidates those events through the AppSurface product-event registry before any host sink or in-memory review model sees them.
Enabled
bool Enabled { get; set; }
Source
Gets or sets a value indicating whether AppSurface Docs metrics features may run.
Remarks
The default is false. When disabled, the docs layout emits no browser collector endpoint, feedback controls stay hidden, hosted metrics collection returns not found, and hosted review returns not found.
BrowserCollector
AppSurfaceDocsBrowserMetricsCollectorOptions BrowserCollector { get; set; }
Source
Gets browser collector settings used by live and static docs pages.
HostedCollection
AppSurfaceDocsHostedMetricsCollectionOptions HostedCollection { get; set; }
Source
Gets hosted collection settings for the package-owned ingestion endpoint.
HostedReview
AppSurfaceDocsHostedMetricsReviewOptions HostedReview { get; set; }
Source
Gets hosted review settings for maintainer-facing search quality diagnostics.
AppSurfaceDocsBrowserMetricsCollectorOptions
SourceBrowser-side docs metrics collector settings.
Enabled
bool Enabled { get; set; }
Source
Gets or sets a value indicating whether the browser collector should forward safe docs metrics events.
Remarks
The default is false. When enabled, AppSurfaceDocsMetricsOptions.Enabled must also be enabled. EndpointUrl may point at an app-root same-origin path such as /docs/_metrics/collect or an HTTPS absolute URL for static CDN deployments.
EndpointUrl
string? EndpointUrl { get; set; }
Source
Gets or sets the browser collector endpoint.
Remarks
Values may be same-origin app-root paths or HTTPS absolute URLs. Protocol-relative URLs, non-HTTP(S) schemes, query strings, fragments, embedded credentials, and secret-like values are rejected during options validation. When hosted collection is enabled and this value is blank, the layout uses the package-owned hosted collection endpoint for the current docs root.
AppSurfaceDocsHostedMetricsCollectionOptions
SourceHosted docs metrics collection settings.
Enabled
bool Enabled { get; set; }
Source
Gets or sets a value indicating whether the package-owned metrics collection endpoint is enabled.
Remarks
The default is false. The endpoint is a public low-trust browser submission boundary: it accepts narrow JSON event DTOs, validates through the product-event registry, updates only bounded in-memory review aggregates, forwards to host-owned product-intelligence sinks when configured, and never echoes submitted values.
AppSurfaceDocsHostedMetricsReviewOptions
SourceHosted search-quality review settings.
Enabled
bool Enabled { get; set; }
Source
Gets or sets a value indicating whether the hosted search-quality diagnostics route is enabled.
Exposure
AppSurfaceDocsHarvestHealthExposure Exposure { get; set; }
Source
Gets or sets when AppSurface Docs should expose the hosted search-quality diagnostics route.
Remarks
The default is AppSurfaceDocsHarvestHealthExposure.DevelopmentOnly. Production hosts that set this to AppSurfaceDocsHarvestHealthExposure.Always must protect the route with host-owned access controls when the search-quality aggregate is sensitive.
AppSurfaceDocsBundleOptions
SourceBundle-mode configuration for AppSurface Docs.
Path
string? Path { get; set; }
Source
Gets or sets the path to the docs bundle payload.
AppSurfaceDocsSidebarOptions
SourceSidebar presentation settings for AppSurface Docs.
NamespacePrefixes
string[] NamespacePrefixes { get; set; }
Source
Gets or sets configured namespace prefixes for sidebar label simplification.
AppSurfaceDocsContributorOptions
SourceContributor-provenance configuration for AppSurface Docs details pages.
Remarks
This contract controls the global contributor-provenance surface. Use Enabled to switch the entire feature on or off for a host, and use page-level contributor metadata to suppress or override individual pages without mutating host-wide defaults.
Enabled
bool Enabled { get; set; }
Source
Gets or sets a value indicating whether contributor provenance rendering is enabled for AppSurface Docs details pages. Disable this when the host should suppress all contributor affordances, even if page-level overrides or trustworthy source paths exist. When false, AppSurface Docs also skips contributor-template startup validation because the feature is globally inactive.
DefaultBranch
string? DefaultBranch { get; set; }
Source
Gets or sets the stable branch name used when expanding configured source and edit URL templates. Required when Enabled is true and either SourceUrlTemplate or EditUrlTemplate is configured, and used as the fallback source ref for symbol links when SourceRef is not configured.
SourceUrlTemplate
string? SourceUrlTemplate { get; set; }
Source
Gets or sets the source-link template. Supported tokens are {branch} and {path}. Configured templates must include {path} so each page expands to its own source location when Enabled is true.
EditUrlTemplate
string? EditUrlTemplate { get; set; }
Source
Gets or sets the edit-link template. Supported tokens are {branch} and {path}. Configured templates must include {path} when Enabled is true. Prefer this when maintainers should land directly in an edit workflow rather than in repository browsing.
SymbolSourceUrlTemplate
string? SymbolSourceUrlTemplate { get; set; }
Source
Gets or sets the source-link template for generated C# API symbols. Supported tokens are {path}, {line}, {branch}, and {ref}. Configured templates must include {path} and {line} when Enabled is true, and unsupported token placeholders are rejected during startup validation. Use {ref} when links should prefer a commit SHA supplied through SourceRef and fall back to DefaultBranch.
SourceRef
string? SourceRef { get; set; }
Source
Gets or sets the source-control ref used for generated C# API symbol links. Prefer a commit SHA when the docs build knows one. When omitted, symbol links that use {ref} fall back to DefaultBranch so hosts can still render moving-branch links intentionally.
LastUpdatedMode
AppSurfaceDocsLastUpdatedMode LastUpdatedMode { get; set; }
Source
Gets or sets the mode used to resolve contributor freshness. The default is AppSurfaceDocsLastUpdatedMode.None so hosts opt into git-backed freshness explicitly instead of paying unexpected snapshot-time git costs. AppSurfaceDocsLastUpdatedMode.Git uses local repository history when a trustworthy source path exists and omits only freshness when git data is unavailable or untrustworthy.
AppSurfaceDocsRoutingOptions
SourceRouting settings for the AppSurface Docs route family and live source surface.
Remarks
AppSurface Docs separates the route-family root from the live docs root. RouteRootPath owns stable entry, archive, and exact-version routes. DocsRootPath owns the live source-backed surface used for current docs, search, and the current search-index payload. For a custom versioned host, use values such as RouteRootPath=/foo/bar and DocsRootPath=/foo/bar/next. Both values are normalized into app-relative paths during AddAppSurfaceDocs() post-configuration.
RouteRootPath
string? RouteRootPath { get; set; }
Source
Gets or sets the app-relative route-family root for this AppSurface Docs instance.
Remarks
The route root is the parent for stable entry, archive, and exact-version routes. When omitted, it defaults to the live docs root with versioning disabled and to /docs with versioning enabled. Relative-looking values are normalized into app-relative paths. For example, foo/bar becomes /foo/bar. Use / for a single-purpose root-mounted docs host. The normalized path must not end with /, include query or fragment segments, or target reserved child routes such as /foo/bar/versions or /foo/bar/v.
DocsRootPath
string? DocsRootPath { get; set; }
Source
Gets or sets the app-relative root path for the live source-backed docs surface.
Remarks
The live root serves current source-backed docs, search, and the current search index. Relative-looking values are normalized into app-relative paths. For example, foo/bar/next becomes /foo/bar/next. When versioning is disabled the default path is the route root. When versioning is enabled the default path is {RouteRootPath}/next, or /docs/next for the default route family. The live root must not collide with the route-family root or its reserved archive/exact-version children when versioning is enabled.
PublicOrigin
string? PublicOrigin { get; set; }
Source
Gets or sets the public origin used when AppSurface Docs renders absolute canonical metadata.
Remarks
This value is optional. When omitted, details pages keep app-relative canonical links so local preview and unknown deployment environments do not leak an inferred host name. When set, it must be an absolute http or https origin such as https://docs.example.com. Do not include RouteRootPath, DocsRootPath, a query string, or a fragment; AppSurface Docs joins the origin to the canonical route it already knows for the current page.
AppSurfaceDocsVersioningOptions
SourceVersioning settings for published AppSurface Docs release trees.
Remarks
Enabling versioning turns on the published-release route contract: AppSurfaceDocsRoutingOptions.RouteRootPath for the recommended release alias, {RouteRootPath}/v/{version} for immutable exact trees, {RouteRootPath}/versions for the archive, and a live preview surface rooted at AppSurfaceDocsRoutingOptions.DocsRootPath. The catalog stays file-based in this slice: runtime consumes a JSON manifest plus prebuilt exact release trees and does not perform Git or bundle resolution at request time. The catalog must describe the recommended version alias plus one or more exact release trees whose exported contents satisfy the exact-tree contract documented in the package README. Public exact release trees must pin releaseManifestSha256 in the catalog so runtime verification can prove local archive integrity before serving mounted archive HTML, scripts, stylesheets, SVG, and search payloads.
Enabled
bool Enabled { get; set; }
Source
Gets or sets a value indicating whether release-tree versioning is enabled.
CatalogPath
string? CatalogPath { get; set; }
Source
Gets or sets the path to the version catalog JSON file.
Remarks
This property is required when Enabled is true. The catalog describes available exact-version trees, the recommended version alias, and release-level status metadata such as support and advisory state. Relative paths resolve from the app content root. The JSON payload is expected to contain a top-level recommended version plus a versions array whose entries point at exported exact-version trees. Each public entry must include releaseManifestSha256 to pin the digest of that tree's .appsurface-docs-release-manifest.json. Entries without the pin are unavailable and are not mounted. A missing, unreadable, or malformed catalog does not crash AppSurface Docs, but it leaves all published releases unavailable until the catalog can be loaded successfully. When Enabled is true and this property is blank, startup validation fails before the app begins serving requests.
TrustedReleaseRootPath
string? TrustedReleaseRootPath { get; set; }
Source
Gets or sets the trusted filesystem root that contains published exact-version release trees.
Remarks
Catalog entries use AppSurfaceDocsPublishedVersion.ExactTreePath values relative to this directory. When this property is blank, AppSurface Docs defaults the trusted release root to the directory containing CatalogPath, which supports the common layout where catalog.json sits beside a releases/ directory. Relative configured values resolve from the app content root. The root and every mounted exact tree must be ordinary directories, not symbolic links, junctions, or other reparse points. Absolute catalog exactTreePath values are invalid; set this property to the old parent directory and make each catalog entry relative when migrating older catalogs.
MaxRewrittenFileSizeBytes
long MaxRewrittenFileSizeBytes { get; set; }
Source
Gets or sets the maximum input size, in bytes, for request-time rewrites of published-tree HTML and search-index files.
Remarks
The default is DefaultMaxRewrittenFileSizeBytes bytes. The value must be between MinMaxRewrittenFileSizeBytes and MaxMaxRewrittenFileSizeBytes. This limit applies only to exported .html files and the root search-index.json file when a published release tree is mounted through AppSurface Docs versioning. Static assets such as CSS, JavaScript, images, and fonts continue to stream normally and are not capped by this option.
AppSurfaceDocsLocalizationOptions
SourceLocalization settings for the live AppSurface Docs source-backed documentation surface.
Remarks
V1 localization applies only to the live source-backed docs surface. Published exact-version release trees keep the existing unlocalized route contract until localized release trees are designed as a separate feature. The built-in defaults keep localization off, use en as the default locale when enabled, prefix localized routes with the locale route segment, and default search to the active locale.
Enabled
bool Enabled { get; set; }
Source
Gets or sets a value indicating whether AppSurface Docs builds locale-aware document graph data.
DefaultLocale
string DefaultLocale { get; set; }
Source
Gets or sets the default locale code. Defaults to en.
Locales
AppSurfaceDocsLocaleOptions[] Locales { get; set; }
Source
Gets or sets the locales supported by the live docs surface.
RouteMode
AppSurfaceDocsLocaleRouteMode RouteMode { get; set; }
Source
Gets or sets how locale prefixes are represented in public live docs routes.
FallbackMode
AppSurfaceDocsLocaleFallbackMode FallbackMode { get; set; }
Source
Gets or sets the global missing-translation fallback behavior.
SearchMode
AppSurfaceDocsLocaleSearchMode SearchMode { get; set; }
Source
Gets or sets the default localized search scope.
AppSurfaceDocsLocaleOptions
SourceDescribes one configured AppSurface Docs locale validated during AppSurface Docs startup.
Remarks
Locale entries are runtime configuration, not loose display hints: Code values must be unique valid BCP-47 tags, and resolved route prefixes must be unique and avoid AppSurface Docs reserved route segments. Omitted Lang and RoutePrefix values fall back to Code, so duplicate codes or route aliases can fail startup validation even when those properties are not explicitly set.
ResolveRoutePrefix
string ResolveRoutePrefix()
Source
Resolves the locale route prefix after applying the documented fallback to Code.
Remarks
This helper centralizes prefix trimming so graph and route-candidate generation do not drift when RoutePrefix is omitted.
Code
string Code { get; set; }
Source
Gets or sets the unique BCP-47 locale code, such as en, fr, or pt-BR.
Remarks
The code is required, must parse as a culture name, and becomes the default Lang and RoutePrefix when those properties are blank.
Label
string? Label { get; set; }
Source
Gets or sets the reader-facing locale label, such as English or Français.
Remarks
The label is optional in Phase 1 and is not validated beyond normal configuration binding.
Lang
string? Lang { get; set; }
Source
Gets or sets the HTML lang value. When omitted, Code is used.
Remarks
Use this only when the rendered HTML language tag should differ from the configured AppSurface Docs locale code. Blank values are treated as omitted and fall back to Code.
Direction
AppSurfaceDocsTextDirection Direction { get; set; }
Source
Gets or sets the text direction for this locale. Defaults to AppSurfaceDocsTextDirection.Ltr.
RoutePrefix
string? RoutePrefix { get; set; }
Source
Gets or sets the route segment used for this locale. When omitted, Code is used.
Remarks
The resolved route prefix must be unique across configured locales and must not collide with reserved AppSurface Docs segments such as search, health, package, version, release, public-section, or asset endpoints. Collisions fail startup validation.
AppSurfaceDocsOptionsValidator
SourceValidates AppSurfaceDocsOptions and rejects unsupported or ambiguous startup configurations.
AppSurfaceDocsThemePreset
SourceDark-family AppSurface Docs theme presets.
AppSurfaceDocsThemeDensity
SourceDensity options for package-owned AppSurface Docs chrome.
AppSurfaceDocsThemeChrome
SourceChrome compactness options for the built-in docs shell.
AppSurfaceDocsMode
SourceEnumerates the supported AppSurface Docs content source modes.
Remarks
Numeric values are part of the public configuration and serialization contract. Do not reorder or renumber existing members; changing these assignments can break persisted configuration, serialized payloads, and consumers. Add new modes by appending members with new explicit values.
AppSurfaceDocsHarvestStartupMode
SourceControls when AppSurface Docs starts its initial source-backed harvest.
Remarks
The numeric values are part of the options binding and serialization contract. Do not renumber or reorder existing members; append new modes with explicit numeric values so persisted configuration remains stable.
AppSurfaceDocsHarvestHealthExposure
SourceEnumerates environment-aware exposure policies for AppSurface Docs harvest health surfaces.
Remarks
Numeric values are part of the public configuration and serialization contract. Do not reorder or renumber existing members; changing these assignments can break persisted configuration, serialized payloads, and consumers. Add new modes by appending members with new explicit values.
AppSurfaceDocsLastUpdatedMode
SourceEnumerates the supported contributor freshness modes for AppSurface Docs details pages.
Remarks
Numeric values are part of the public configuration and serialization contract. Do not reorder or renumber existing members; changing these assignments can break persisted configuration, serialized payloads, and consumers. Add new modes by appending members with new explicit values.
AppSurfaceDocsLocaleRouteMode
SourceEnumerates supported locale route modes.
Remarks
Numeric values are part of the public configuration contract. Append new modes with new explicit values.
AppSurfaceDocsLocaleFallbackMode
SourceEnumerates supported global localization fallback modes.
Remarks
Numeric values are part of the public configuration contract. Append new modes with new explicit values.
AppSurfaceDocsLocaleSearchMode
SourceEnumerates supported localized search defaults.
Remarks
Numeric values are part of the public configuration contract. Append new modes with new explicit values.
AppSurfaceDocsTextDirection
SourceEnumerates supported text directions for localized docs pages.
Remarks
Numeric values are part of the public configuration contract. Append new directions with new explicit values.
AppSurfaceDocsHarvestDefaultExclusionOptions
SourceControls package-defined default harvest exclusion groups.
Remarks
DisabledGroups disables selected default groups by stable group ID. AllowGlobs opts paths back into selected default groups by stable group ID. Unknown group IDs fail options validation.
Default-exclusion allows are group-aware. If a path matches multiple enabled default groups, every matched group must either be disabled or have an allow glob matching the path. Configured excludes still win after an allow.
DisabledGroups
string[] DisabledGroups { get; set; }
Source
Gets or sets default group IDs to disable for the containing scope.
AllowGlobs
Dictionary<string, string[]> AllowGlobs { get; set; }
Source
Gets or sets allow globs by default group ID.
AppSurfaceDocsJavaScriptHarvestOptions
SourceJavaScript public API harvest path policy, parser, grouping, and strict-health settings.
Remarks
JavaScript harvesting is enabled by default and scans policy-approved .js files for explicit @public browser-contract doclets. Unannotated JavaScript is ignored. Global AppSurfaceDocsHarvestOptions.Paths rules apply first, then these source-specific include, exclude, and default-exclusion settings refine the JavaScript candidate set. File and directory reparse points are skipped before source reads or directory descent, including when a configured include points at a symlink or junction. IncludeGlobs is an optional narrowing boundary, not an enable switch. GroupNameRules names already-eligible JavaScript source trees but never includes files on its own. Tags such as @internal, @private, and @ignore always exclude a doclet from the generated public API surface.
Enabled
bool Enabled { get; set; }
Source
Gets or sets a value indicating whether JavaScript public API harvesting is enabled.
IncludeGlobs
string[] IncludeGlobs { get; set; }
Source
Gets or sets JavaScript-specific repository-relative include globs.
Remarks
Patterns use forward-slash Microsoft.Extensions.FileSystemGlobbing matching. Examples include Web/ForgeTrust.RazorWire/assets/contracts/razorwire-public-contracts.js for a single file or src/widgets/**/*.js for a bounded source tree. Include globs compose with global includes using AND semantics. Blank entries are ignored during options normalization. Configured include roots that resolve to file-system reparse points are skipped and reported through appsurfacedocs.javascript.reparse_point_skipped; point includes at real source files or directories.
ExcludeGlobs
string[] ExcludeGlobs { get; set; }
Source
Gets or sets JavaScript-specific repository-relative exclude globs.
Remarks
Excludes win over includes and default-exclusion allows. The default skips minified bundles so generated vendor assets do not dominate parse time or create noisy public API diagnostics. Build output, hidden directories, and test directories are controlled through DefaultExclusions.
DefaultExclusions
AppSurfaceDocsHarvestDefaultExclusionOptions DefaultExclusions { get; set; }
Source
Gets or sets JavaScript-specific default-exclusion group controls.
GroupNameRules
AppSurfaceDocsJavaScriptGroupNameRule[] GroupNameRules { get; set; }
Source
Gets or sets ordered JavaScript API group naming rules for policy-approved source paths.
Remarks
Rules are evaluated in order and the first matching rule supplies the JavaScript API family name only when a public doclet does not provide a nonblank @namespace or @module tag. Rule globs use the same repository-relative forward-slash syntax as IncludeGlobs. Naming rules do not include or exclude source files; global and JavaScript harvest path policy still decides which files are parsed.
RequirePublicTag
bool RequirePublicTag { get; set; }
Source
Gets or sets a value indicating whether supported doclets must include @public.
Remarks
Broad default discovery always requires @public, even when this setting is false. The compatibility escape applies only when IncludeGlobs contains at least one explicit JavaScript source boundary.
StrictHealth
bool StrictHealth { get; set; }
Source
Gets or sets a value indicating whether default JavaScript discovery should participate in strict aggregate harvest health.
Remarks
The default is false, which makes broad JavaScript discovery best-effort: empty results, parse failures, read failures, and timeouts produce diagnostics but do not mask or cause strict Markdown/C# harvest outcomes. JavaScript always participates in strict health when IncludeGlobs is nonempty.
RequireCompleteEventDoclets
bool RequireCompleteEventDoclets { get; set; }
Source
Gets or sets a value indicating whether incomplete public JavaScript event doclets should fail harvest health.
Remarks
The default is false, which preserves best-effort event documentation: incomplete public events render and emit Models.DocHarvestDiagnosticCodes.JavaScriptIncompletePublicDoclet warnings. Set this to true for CI and release verification when public browser events must document @target, @firesWhen, and either at least one valid @property detail.* field or @detail none. This option applies only to incomplete public event doclets and does not make parse, oversized-file, unsupported-shape, or malformed-doclet diagnostics strict; those remain controlled by StrictHealth or explicit IncludeGlobs.
VerifyEventDispatches
bool VerifyEventDispatches { get; set; }
Source
Gets or sets a value indicating whether public JavaScript event doclets should be compared to literal dispatch evidence.
Remarks
The default is false. When enabled, the built-in JavaScript harvester compares intentional public @event doclets with direct literal dispatchEvent(new CustomEvent("event:name", ...)) calls found in the same policy-approved JavaScript harvest inputs. Mismatches emit warning diagnostics only; they do not publish inferred docs and do not make strict harvest health fail. The v1 verifier matches literal .js CustomEvent dispatches only; helper-dispatched calls, dynamic or constant event names, variable-held events, new Event(...), and TypeScript-only sources are intentionally skipped and should be treated as documented verifier limitations instead of release regressions.
MaxFileSizeBytes
long MaxFileSizeBytes { get; set; }
Source
Gets or sets the largest JavaScript file, in bytes, that the harvester will parse.
Remarks
Oversized files are skipped with a harvest diagnostic so generated bundles do not dominate snapshot time or make parser failures noisy. The default comes from the parser decision spike and covers the current RazorWire and AppSurface Docs authored browser assets with headroom.
AppSurfaceDocsJavaScriptGroupNameRule
SourceNames JavaScript API groups for already-eligible source paths that do not declare @namespace or @module.
Remarks
AppSurface Docs evaluates rules in configured order and uses the first rule whose IncludeGlobs match the repository-relative JavaScript source path. Prefer explicit doclet tags when the source itself owns a stable API family name; use rules to keep package-owned contract manifests readable without repeating the same tag in every doclet.
Name
string? Name { get; set; }
Source
Gets or sets the reader-facing JavaScript API family name to use for matching source paths.
IncludeGlobs
string[] IncludeGlobs { get; set; }
Source
Gets or sets repository-relative JavaScript source globs covered by this naming rule.
Remarks
Patterns are matched case-insensitively with the same safe glob syntax as JavaScript harvest include globs. The rule only names files that the normal harvest path policy already accepted.
AppSurfaceDocsAssetVersioner
SourceAppends content-derived version keys to AppSurface Docs asset URLs.
Remarks
AppSurface Docs often exposes package assets through friendly route-local aliases such as /docs/search.css. ASP.NET Core's standard file version provider cannot always resolve those aliases because they are endpoint redirects or web-root preview routes rather than direct static-web-asset paths. This service hashes the package-embedded asset bytes instead, then applies the resulting version to the public URL that the current docs surface should render. Use it for AppSurface Docs-owned CSS and JavaScript assets that must survive browser, CDN, or service-worker caches across deployments. Do not use it for reader-authored document links or external CDN URLs.
BuildVersionedDocsAssetUrl
string BuildVersionedDocsAssetUrl(DocsUrlBuilder docsUrlBuilder, string assetName)
Source
Builds a versioned current-surface URL for an AppSurface Docs docs asset.
Parameters
docsUrlBuilderThe URL builder for the active AppSurface Docs surface.assetNameThe docs asset file name, such assearch.cssorsearch-client.js.
Returns
The current-surface asset URL with a content-derived v query parameter, or the unversioned URL when the packaged asset cannot be found.
AppendVersion
string AppendVersion(string url, string embeddedAssetPath)
Source
Appends a version key to a AppSurface Docs-owned asset URL.
Parameters
urlThe public URL that should be rendered.embeddedAssetPathThe asset path under the AppSurface Docs embedded asset root.
Returns
url with the content version appended, preserving existing query strings and fragments. If the URL already has a v parameter or the asset cannot be found, the original URL is returned.
AppSurfaceDocsHarvestPathOptions
SourceGlobal repository-relative harvest path policy settings shared by every built-in AppSurface Docs harvester.
Remarks
Patterns use normalized repository-relative paths with / separators. Empty include globs mean "use each harvester's normal candidate set." Nonempty include globs define the global public-docs territory that source-specific include globs can refine but cannot bypass. Exclude globs are final denials and win over includes and default-exclusion allows.
IncludeGlobs
string[] IncludeGlobs { get; set; }
Source
Gets or sets optional repository-wide include globs.
ExcludeGlobs
string[] ExcludeGlobs { get; set; }
Source
Gets or sets repository-wide exclude globs that win over includes and default-exclusion allows.
DefaultExclusions
AppSurfaceDocsHarvestDefaultExclusionOptions DefaultExclusions { get; set; }
Source
Gets or sets controls for package-defined default exclusion groups.
VcsIgnore
AppSurfaceDocsHarvestVcsIgnoreOptions VcsIgnore { get; set; }
Source
Gets or sets repository-owned VCS ignore file integration for source harvesting.
Remarks
AppSurface Docs reads Git .gitignore files under the resolved repository root by default so legacy generated, vendored, and package-manager-owned trees do not become published documentation accidentally. Use AppSurfaceDocsHarvestVcsIgnoreOptions.AllowGlobs for selected public documentation that intentionally lives under an ignored path, or set AppSurfaceDocsHarvestVcsIgnoreOptions.Enabled to false when a host wants to ignore repository VCS policy entirely.
AppSurfaceDocsHarvestVcsIgnoreOptions
SourceControls how AppSurface Docs applies repository-owned Git ignore files during source harvesting.
Remarks
This option is intentionally scoped to Git .gitignore files that live under the resolved source root. AppSurface Docs does not read machine-local Git excludes, global Git excludes, or .git/info/exclude in v1 so harvest behavior stays reproducible across local development, CI, static export, and package consumers.
Enabled
bool Enabled { get; set; }
Source
Gets or sets a value indicating whether Git .gitignore files should participate in harvest filtering.
AllowGlobs
string[] AllowGlobs { get; set; }
Source
Gets or sets AppSurface repository-relative globs that restore selected paths excluded only by VCS ignore rules.
Remarks
These patterns use the same safe AppSurface glob syntax as AppSurfaceDocsHarvestPathOptions.IncludeGlobs and AppSurfaceDocsHarvestPathOptions.ExcludeGlobs. They are not Git-ignore patterns. An allow glob can neutralize a VCS-ignore exclusion, but it cannot override AppSurface default exclusions or configured AppSurface exclude globs.
AppSurfaceDocsServiceCollectionExtensions
SourceRegisters the AppSurface Docs dependency injection and options normalization pipeline.
Remarks
This extension binds AppSurfaceDocsOptions from configuration, rehydrates omitted nested option objects such as AppSurfaceDocsOptions.Harvest, AppSurfaceDocsOptions.Routing, and AppSurfaceDocsOptions.Versioning with their default containers, normalizes caller-provided string settings, and validates the final shape on startup. Callers should use this once per application when they want the standard AppSurface Docs harvesting, routing, preview, and versioned published-release services to be available to downstream modules and controllers.
AddAppSurfaceDocs
IServiceCollection AddAppSurfaceDocs(this IServiceCollection services)
Source
Adds the AppSurface Docs package services, normalized options, and routing helpers to the service collection.
Parameters
servicesThe target service collection.
Returns
The same service collection for chaining.
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 AppSurfaceDocsRoutingOptions.RouteRootPath and AppSurfaceDocsRoutingOptions.DocsRootPath through DocsUrlBuilder.NormalizeRouteRootPath(string?, string, bool) and DocsUrlBuilder.NormalizeDocsRootPath(string?, bool), trims AppSurfaceDocsVersioningOptions.CatalogPath, normalizes AppSurfaceDocsLocalizationOptions.DefaultLocale to en when blank, trims locale AppSurfaceDocsLocaleOptions.Code, AppSurfaceDocsLocaleOptions.Label, AppSurfaceDocsLocaleOptions.Lang, and AppSurfaceDocsLocaleOptions.RoutePrefix values while skipping null locale entries, and removes blank or duplicate sidebar namespace prefixes. Callers that omit AppSurfaceDocsOptions.Routing, AppSurfaceDocsOptions.Versioning, or AppSurfaceDocsOptions.Localization can therefore still rely on a fully populated options object after registration. When AppSurfaceDocsHarvestOptions.FailOnFailure is enabled, the registered startup preflight fails the host only when the aggregate harvest health is failed.
When AppSurfaceDocsRoutingOptions.DocsRootPath is omitted or whitespace, the live docs root is derived from the normalized AppSurfaceDocsRoutingOptions.RouteRootPath through DocsUrlBuilder.ResolveDefaultDocsRootPath(string, bool). For example, AppSurfaceDocs:Routing:RouteRootPath=/foo/bar with versioning enabled produces /foo/bar/next as the default live root. Callers that set both AppSurfaceDocsRoutingOptions.RouteRootPath and AppSurfaceDocsRoutingOptions.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, the internal docs recovery-link builder, AppSurfaceDocsAssetVersioner, and AppSurfaceDocsVersionCatalogService as singleton downstream services alongside the standard harvesters, memo cache, and DocAggregator. AppSurfaceDocsAssetVersioner supplies content-derived cache keys for AppSurface Docs-owned CSS and JavaScript assets rendered by the package views. It also registers RazorWire through RazorWireServiceCollectionExtensions and adds harvest observability services such as AppSurfaceDocsHarvestCoordinator, AppSurfaceDocsHarvestProgressReporter, and AppSurfaceDocsHarvestPathPolicy.
If an IRazorWireStreamAuthorizer is already registered, AppSurface Docs wraps that result-bearing authorizer so hidden harvest routes deny first and AppSurfaceDocs:Diagnostics:OperatorReadPolicy, when configured, authorizes the docs-owned harvest-progress channel before custom authorizers may narrow access. Existing IRazorWireChannelAuthorizer registrations still work through the legacy bool facade when plain allow/deny compatibility is sufficient and no shared read policy is configured. Register a custom authorizer before calling this method to participate in that wrapper. Registering an IRazorWireStreamAuthorizer after this method replaces the AppSurface Docs wrapper for normal stream authorization, but the docs-owned harvest stream still passes through the hidden-route and shared read-policy gate before that replacement authorizer can narrow access. Use AppSurfaceDocsStreamAuthorization.IsHarvestProgressChannel(string?) in host authorizers that need to distinguish the package stream from application streams. Built-in RazorWire allow-all/deny-all authorizers are not considered custom authorization for that docs-owned stream. Call this method once during startup; repeated registration can nest authorizer wrappers and obscure the intended channel policy.
AppSurfaceDocs:Diagnostics:OperatorReadPolicy names an optional host-owned ASP.NET Core authorization policy for exposed diagnostics read routes such as {DocsRootPath}/_harvest, {DocsRootPath}/_routes, and {DocsRootPath}/_routes.json. It also protects {DocsRootPath}/_health and {DocsRootPath}/_health.json when AppSurfaceDocs:Harvest:Health:AuthorizationPolicy is absent. The health policy remains a health-only compatibility policy and wins for health routes when both are configured. Hosts that configure either policy must register authentication before authorization in the endpoint-aware middleware phase. Consumers that resolve AppSurfaceDocsOptions 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.
AppSurfaceDocsUrlHelperExtensions
SourceProvides Razor view helpers for emitting app-relative AppSurface Docs links that honor the active request path base.
PathBaseAware
string PathBaseAware(this IUrlHelper url, string? href)
Source
Rewrites rooted app-relative href values through IUrlHelper.Content(string) so mounted hosts keep their current PathBase, while leaving non-rooted URLs unchanged.
Parameters
urlThe active URL helper for the rendered view.hrefThe href to normalize for rendering.
Returns
A path-base-aware href for rooted docs links, the original non-rooted href for relative/external links, or an empty string when href is blank. Protocol-relative URLs such as //cdn.example.com/app.css are preserved as-is so they do not get mistaken for app-relative docs links.
AppSurfaceDocsMarkdownHarvestOptions
SourceMarkdown-specific harvest path policy and resource-limit settings.
Remarks
These options refine AppSurfaceDocsHarvestOptions.Paths for Markdown source files and the root LICENSE candidate. Source-specific includes compose with global includes using AND semantics, and source-specific excludes win over includes and default-exclusion allows. The byte limits are pre-read guards for Markdown body files and paired metadata sidecars; they do not limit Markdig parser complexity, AST depth, execution time, or cancellation behavior after a file has been admitted for parsing.
IncludeGlobs
string[] IncludeGlobs { get; set; }
Source
Gets or sets Markdown-specific include globs.
ExcludeGlobs
string[] ExcludeGlobs { get; set; }
Source
Gets or sets Markdown-specific exclude globs.
DefaultExclusions
AppSurfaceDocsHarvestDefaultExclusionOptions DefaultExclusions { get; set; }
Source
Gets or sets Markdown-specific default-exclusion group controls.
MaxFileSizeBytes
long MaxFileSizeBytes { get; set; }
Source
Gets or sets the largest Markdown body file, in bytes, that the harvester will read and parse.
Remarks
The default is DefaultMaxFileSizeBytes bytes. Files that exceed this limit are skipped before the file is read, before inline front matter is parsed, and before Markdig receives the Markdown body. Inline front matter is part of the Markdown body file and is therefore governed by this limit. Use path excludes for generated or accidental large files, and raise this limit only for intentional authored Markdown pages.
MaxMetadataFileSizeBytes
long MaxMetadataFileSizeBytes { get; set; }
Source
Gets or sets the largest paired Markdown metadata sidecar, in bytes, that the harvester will read and parse.
Remarks
The default is DefaultMaxMetadataFileSizeBytes bytes. Paired .md.yml and .md.yaml metadata sidecars that exceed this limit are ignored before YAML parsing, while the Markdown body continues to publish when it is within MaxFileSizeBytes. This setting does not apply to inline front matter.