Pennington.Content.IContentService

namespace Pennington.Content;

/// Discovers and provides content for the pipeline.
public interface IContentService
{
    /// Default section label applied to discovered items that do not supply one via front matter.
    
string DefaultSectionLabel { get; }

    /// Discover all content items this service is responsible for.
    
IAsyncEnumerable<DiscoveredItem> DiscoverAsync();

    /// Navigation entries for table of contents.
    
Task<ImmutableList<ContentTocItem>> GetContentTocEntriesAsync();

    /// Static files to copy to output (images, downloads, etc.)
    
Task<ImmutableList<ContentToCopy>> GetContentToCopyAsync();

    /// Files to write into the build output directory.
    
Task<ImmutableList<ContentToCreate>> GetContentToCreateAsync();

    /// Cross-references for xref resolution.
    
Task<ImmutableList<CrossReference>> GetCrossReferencesAsync();

    /// Entries that should appear in the search index and llms.txt. Default: returns GetContentTocEntriesAsync. That is correct when "shown in navigation" ≡ "discoverable via search" — the default holds for markdown, because MarkdownContentService's TOC entries already honor search: and llms: front-matter fields via ExcludeFromSearch / ExcludeFromLlms.Override when the two sets diverge — for example, RazorPageContentService emits sidecar-less pages here (so users can search for them) without adding them to navigation (which would clutter the TOC with auto-titled entries).Implementors of custom content services that build ContentTocItems directly: set ExcludeFromSearch and ExcludeFromLlms from your metadata's Search / Llms flags, or per-page opt-outs will be silently ignored.
    
async Task<ImmutableList<ContentTocItem>> GetIndexableEntriesAsync();

    /// Redirect sources this service emits (each item's Source is a RedirectSource). Consumed by RedirectContentService to build the unified redirect map without iterating every service's DiscoverAsync — which would force services that have no redirects to pay the full cost of discovery just to return nothing. Default: empty. Services backed by front-matter records that implement IRedirectable override this.
    
Task<ImmutableList<DiscoveredItem>> GetRedirectSourcesAsync();

    /// Relative priority for ordering results in the search index (higher values rank first).
    
int SearchPriority { get; }
}