Pennington.DocSite.Services.ContentResolver

namespace Pennington.DocSite.Services;

/// Resolves content pages by URL for the DocSite. Locale-aware: detects locale from URL, searches locale-specific content first, then falls back to the default locale. Works with all content sources (markdown, Razor pages, custom services).
public class ContentResolver
{
    /// Creates a new resolver with the supplied content services and options.
    
public ContentResolver(
    IEnumerable<IContentService> services,
    FrontMatterParser parser,
    IContentRenderer renderer,
    NavigationBuilder navBuilder,
    DiagnosticContext diagnostics,
    LocalizationOptions localization,
    DocSiteOptions docSiteOptions);

    /// Get alternate language versions for a page URL. Always includes all configured locales — fallback resolution handles missing translations. Delegates URL math to GetAlternateLanguages and wraps results with ContentRoute for DocSite consumption.
    
public Task<ImmutableList<AlternateLanguagePage>> GetAlternateLanguagesAsync(string url);

    /// Get rendered content for a URL. Returns null if not found. Handles locale detection and fallback to default locale.
    
public async Task<ResolvedContent?> GetContentByUrlAsync(string url);

    /// Get navigation info for a URL, filtered by locale.
    
public async Task<NavigationInfo?> GetNavigationInfoAsync(string url);

    /// Get navigation info (prev/next/breadcrumbs) scoped to an area. When area is null, falls back to the full-site navigation.
    
public async Task<NavigationInfo?> GetNavigationInfoForAreaAsync(
    string url, ContentArea? area);

    /// Get all TOC items, optionally filtered by locale.
    
public async Task<IReadOnlyList<ContentTocItem>> GetTocItemsAsync(string? locale = null);

    /// Get TOC items scoped to a specific area. Filters by area slug matching HierarchyParts[0] and strips the area prefix, mirroring the locale-stripping pattern in NavigationBuilder.
    
public async Task<IReadOnlyList<ContentTocItem>> GetTocItemsForAreaAsync(
    string? locale, ContentArea? area);

    /// Resolves which content area the given URL belongs to, based on the first path segment matching a configured area slug. Returns null if no area matches.
    
public ContentArea? ResolveCurrentArea(string url);
}