Controllers
DocsController
SourceController for serving documentation pages.
Index
Task<IActionResult> Index()
Source
Displays the documentation index view containing either curated proof paths from the repository-root landing doc metadata or the neutral docs landing fallback.
Returns
A view result whose model is a DocLandingViewModel. The model includes curated featured cards when the repository-root README.md metadata authors featured_page_groups through inline front matter or a paired sidecar such as README.md.yml; otherwise it includes the neutral fallback landing data.
VersionEntry
IActionResult VersionEntry()
Source
Displays the stable docs entry fallback when versioning is enabled but the recommended released tree is not mounted.
Returns
A view result describing the available released versions plus the current preview surface, or a redirect to the live docs home when versioning is disabled.
Versions
IActionResult Versions()
Source
Displays the public docs version archive.
Returns
A view result that lists the published versions described by the configured version catalog, or a redirect to the live docs home when versioning is disabled.
Section
Task<IActionResult> Section(string sectionSlug)
Source
Enters one normalized public documentation section.
Parameters
sectionSlugThe stable slug for the public section.
Returns
A redirect to the authored landing doc when one exists, otherwise a grouped section fallback or unavailable view.
Details
Task<IActionResult> Details(string path)
Source
Displays the full or partial details view for a documentation item identified by the given path.
Parameters
pathThe public docs route, redirect alias, or.partial.htmlresource identifier of the documentation item to retrieve. Full-page source-shaped Markdown routes for public pages redirect to the clean canonical route.
Returns
An IActionResult rendering the details view or the doc-content RazorWire frame; returns NotFoundResult when the path is invalid or no document is found after fallback resolution.
Remarks
Partial requests ending in .partial.html are resolved through the same DocAggregator.GetDocDetailsAsync(string, CancellationToken) flow as full-page requests. When a partial path resolves to an /index resource, such as /index.partial.html, the action transparently retries the parent document before returning NotFoundResult. Successful requests load the complete docs corpus and public-section snapshots with DocAggregator.GetDocsAsync(CancellationToken) and DocAggregator.GetPublicSectionsAsync(CancellationToken), then build the response model with BuildDetailsViewModel. All aggregator calls observe HttpContext.RequestAborted. Visible caller side effects are limited to returning either the full details view or a doc-content frame for partial navigation.
Search
Task<IActionResult> Search()
Source
Displays the dedicated docs search workspace shell.
Returns
A ViewResult whose model is a SearchPageViewModel describing the search shell and its server-rendered recovery paths.
Remarks
The action returns a SearchPageViewModel immediately so the workspace can render starter, loading, and retry UI before the client downloads the search index. Fallback link generation shares a linked cancellation token with the current request and is capped by SearchShellFallbackBudget so slow aggregation does not block the shell from rendering. If aggregation times out or throws, the view still renders with default recovery links.
SearchIndex
Task<IActionResult> SearchIndex()
Source
Returns docs search index data for live-hosted docs.
Returns
A JSON result containing searchable document metadata, including normalized page-type badge fields that keep search result rendering consistent with the built-in landing and details experiences. When HttpRequest.PathBase is non-empty, only documents[*].path values that already start with / are rebased onto that path base before serialization so a mounted app returns links like /some-base/docs/guide.html instead of /docs/guide.html.
Remarks
The path-base rewrite is intentionally narrow. Only rooted documents[*].path values are prefixed; blank, missing, or already non-rooted values such as guide.html remain unchanged. The rewrite trims trailing slashes from the request path base before concatenation, so /some-base/ and /some-base produce the same output. For example, a typed payload that contains documents[0].path = "/docs/guide.html" becomes /some-base/docs/guide.html when the request path base is /some-base. This action always receives the typed DocsSearchIndexPayload produced by DocAggregator.GetSearchIndexPayloadAsync(System.Threading.CancellationToken); raw JSON payloads without a top-level documents array are outside this method's contract and must be handled before this action is invoked. The rewrite is idempotent when HttpRequest.PathBase is null, empty, or /.
HarvestHealth
Task<IActionResult> HarvestHealth()
Source
Displays the redacted operator-facing harvest health page for the current live docs surface.
Returns
A health page when health routes are exposed for the current environment; otherwise NotFoundResult. Healthy and empty snapshots return HTTP 200. Degraded and failed snapshots render the same page with HTTP 503 so local verification and CI checks can fail quickly.
HarvestHealthJson
Task<IActionResult> HarvestHealthJson()
Source
Returns redacted machine-readable harvest health for the current live docs surface.
Returns
A JSON health response when health routes are exposed for the current environment; otherwise NotFoundResult. Healthy and empty snapshots return HTTP 200 with verification.ok=true. Degraded and failed snapshots return HTTP 503 with verification.ok=false.
ShouldRefreshCache
bool ShouldRefreshCache(IQueryCollection query)
Source
Determines whether the search index cache should be refreshed based on the presence of a "refresh" query parameter.
Parameters
queryThe collection of query parameters from the HTTP request.
Returns
true if the cache should be refreshed; otherwise, false.
CanRefreshCache
bool CanRefreshCache()
Source
Checks whether the current user has permission to initiate a cache refresh.
Returns
true if the user is authenticated; otherwise, false.
PrefixSearchIndexPathsForPathBase
DocsSearchIndexPayload PrefixSearchIndexPathsForPathBase(DocsSearchIndexPayload payload, string? requestPathBase)
Source
Prefixes rooted search-document paths in a cached search-index payload for the active request path base.
Parameters
payloadThe cached search-index payload whose document paths may need rebasing.requestPathBaseThe current request path base that should be prepended when it is non-empty and not/.
Returns
The original payload when no rewrite is needed; otherwise a cloned payload whose rooted DocsSearchIndexDocument.Path values are prefixed with the normalized path base.
Remarks
This helper operates on the typed DocsSearchIndexPayload contract, which always exposes a top-level DocsSearchIndexPayload.Documents list. It does not inspect or reshape arbitrary JSON payloads, so callers that hold raw JSON without a top-level documents array must deserialize or otherwise handle that mismatch before calling this method. Within the typed payload, only rooted DocsSearchIndexDocument.Path values are rewritten. Non-rooted, blank, or otherwise unchanged values such as guide.html are returned as-is, so callers should supply leading-slash browser paths for docs-local navigation when rebasing is expected. For example, rebasing a payload that contains documents[0].path = "/docs/guide.html" with /some-base/ produces /some-base/docs/guide.html. The supplied path base is trimmed of trailing slashes before concatenation, and the method is idempotent when requestPathBase is null, empty, or /.
IsApiSurfaceDoc
bool IsApiSurfaceDoc(DocNode doc)
Source
Determines whether a documentation node should render with the API reference reading surface.
Remarks
Non-Markdown generated docs use the API surface by default because RazorDocs cannot assume extensionless generated pages have authored prose rhythm. Markdown docs opt into the API surface only when page_type normalizes to api or api-reference. Extensionless authored content is therefore treated as generated API/reference content unless a future harvester exposes a stronger authorship signal.
IsApiSurfacePageType
bool IsApiSurfacePageType(string? pageType)
Source
Determines whether raw page-type metadata explicitly requests the API reference reading surface.
Remarks
Values are normalized with DocMetadataPresentation.NormalizeToken(string?) before comparison, so values such as api_reference and API Reference match api-reference. Null or blank metadata does not opt a Markdown document into the API surface.
IsMarkdownDoc
bool IsMarkdownDoc(string path)
Source
Determines whether a source path represents authored Markdown by checking known Markdown filename suffixes.
Remarks
Matching is case-insensitive and currently recognizes .md and .markdown. Callers should pass a non-null harvested path; extensionless paths are intentionally treated as non-Markdown generated docs.