Services
IRazorDocsHtmlSanitizer
Sanitizes rendered RazorDocs HTML using the package's docs-specific allowlist.
Sanitize
string Sanitize(string html)
Sanitizes the provided HTML fragment.
Parameters
htmlThe HTML fragment to sanitize.
Returns
The sanitized HTML fragment.
DocAggregator
Service responsible for aggregating documentation from multiple harvesters and caching the results.
GetDocsAsync
Task<IReadOnlyList<DocNode>> GetDocsAsync(CancellationToken cancellationToken = default)
Retrieves all harvested documentation nodes sorted by their Path.
Parameters
cancellationTokenAn optional token to observe for cancellation requests.
Returns
A read-only list of all DocNode objects ordered by their Path.
GetDocByPathAsync
Task<DocNode?> GetDocByPathAsync(string path, CancellationToken cancellationToken = default)
Retrieves a specific documentation node for the specified repository path.
Parameters
pathThe documentation path to look up.cancellationTokenAn optional token to observe for cancellation requests.
Returns
The DocNode if found, or null if no node exists for the given path.
GetSearchIndexPayloadAsync
Task<object> GetSearchIndexPayloadAsync(CancellationToken cancellationToken = default)
Returns the docs search-index payload generated during docs aggregation.
Parameters
cancellationTokenAn optional token to observe for cancellation requests.
Returns
A JSON-serializable payload containing index metadata and documents.
InvalidateCache
void InvalidateCache()
Invalidates the cached docs snapshot so docs and search-index are rebuilt on next access.
GetCachedDocsSnapshotAsync
Task<CachedDocsSnapshot> GetCachedDocsSnapshotAsync()
Retrieves the cached docs snapshot, harvesting docs and generating the search-index payload when absent.
Returns
A cached snapshot containing both docs and search-index payload.
Remarks
When harvesting, each configured harvester is invoked; failures from individual harvesters are caught and logged. Contents are sanitized before being cached. If multiple nodes share the same Path, a warning is logged and the first occurrence is retained. The search-index payload is generated from the same harvested snapshot. Caller cancellation does not cancel shared snapshot computation; callers can cancel their own wait. Harvester execution is bounded by a timeout so a single slow harvester cannot block snapshot regeneration indefinitely. The memoized cache entry is created with a 5-minute absolute expiration.
BuildSearchIndexPayload
(object Payload, int RecordCount) BuildSearchIndexPayload(IEnumerable<DocNode> docs)
Builds the search-index payload from the harvested documentation nodes.
Parameters
docsThe documentation nodes to index.
Returns
A tuple containing the serializable payload and the number of records indexed.
NormalizeSearchText
string NormalizeSearchText(string? text)
Decodes HTML entities and normalizes whitespace in the provided text for search indexing.
Parameters
textThe text to normalize.
Returns
The normalized text.
BuildSearchDocUrl
string BuildSearchDocUrl(string path)
Constructs a browser-facing URL for a documentation path.
Parameters
pathThe relative documentation path.
Returns
A URL string starting with "/docs".
TruncateSnippetAtWordBoundary
string TruncateSnippetAtWordBoundary(string text, int maxLength)
Truncates a text snippet at the last word boundary before the maximum length is exceeded.
Parameters
textThe text to truncate.maxLengthThe maximum allowed length of the snippet.
Returns
The truncated text with an ellipsis if it was shortened.
MergeNamespaceReadmes
void MergeNamespaceReadmes(List<DocNode> nodes)
Merges README content into the corresponding namespace overview pages.
Parameters
nodesThe list of documentation nodes to process; README nodes used for merging are removed from this list.
MergeNamespaceIntroIntoContent
string MergeNamespaceIntroIntoContent(string namespaceContent, string readmeContent)
Inserts README content into a namespace overview page after the auto-generated namespace groups.
Parameters
namespaceContentThe auto-generated HTML content for the namespace page.readmeContentThe HTML content from the README file.
Returns
The merged HTML content.
FindMatchingSectionEnd
int FindMatchingSectionEnd(string content, int sectionStart)
Finds the index of the closing </section> tag that matches a <section> tag starting at the specified index.
Parameters
contentThe HTML content to search.sectionStartThe starting index of the <section> tag.
Returns
The index of the closing tag, or -1 if no match is found.
IsReadmePath
bool IsReadmePath(string path)
Determines whether the specified path points to a documentation README file.
Parameters
pathThe path to check.
Returns
true if the path identifies a README.md file; otherwise, false.
ExtractNamespaceNameFromNamespacePath
string ExtractNamespaceNameFromNamespacePath(string path)
Extracts the dotted namespace name from a documentation path under the "Namespaces/" directory.
Parameters
pathThe path to process.
Returns
The extracted namespace name.
ExtractNamespaceNameFromReadmePath
2 overloads
string? ExtractNamespaceNameFromReadmePath(string path)
Attempts to extract a namespace name from a README path by looking at the parent directory name.
Parameters
pathThe README path to process.
Returns
The extracted namespace name, or null if it cannot be determined.
string? ExtractNamespaceNameFromReadmePath(string path, IEnumerable<string>? knownNamespaceNames)
Extracts a namespace name from a README path, optionally matching against a list of known namespaces.
Parameters
pathThe README path to process.knownNamespaceNamesOptional list of known namespaces to match directory segments against.
Returns
The extracted namespace name, or null if it cannot be determined.
NormalizeLookupPath
string NormalizeLookupPath(string path)
Normalizes a documentation path for lookup by trimming slashes and removing fragment anchors.
Parameters
pathThe path to normalize.
Returns
The normalized lookup path.
NormalizeCanonicalPath
string NormalizeCanonicalPath(string path)
Normalizes a documentation path for canonicalization by trimming slashes and normalizing separators.
Parameters
pathThe path to normalize.
Returns
The normalized canonical path.
GetFragment
string? GetFragment(string path)
Extracts the fragment anchor (after the '#') from a documentation path.
Parameters
pathThe path to process.
Returns
The fragment string, or null if no fragment is present.
BuildCanonicalPath
string BuildCanonicalPath(string sourcePath)
Constructs a canonical browser-facing path (e.g., with .html extension) for a given documentation source path.
Parameters
sourcePathThe relative path to the documentation source.
Returns
The canonical browser-facing path.
RazorDocsHtmlSanitizer
RazorDocs-specific HTML sanitizer configuration.
MarkdownHarvester
Harvester implementation that scans Markdown source files and converts them into documentation nodes.
HarvestAsync
Task<IReadOnlyList<DocNode>> HarvestAsync(string rootPath, CancellationToken cancellationToken = default)
Harvests Markdown files under the specified root directory and converts each into a DocNode containing a display title, relative path, and generated HTML.
Parameters
rootPathThe root directory to search recursively for `.md` files.cancellationTokenAn optional token to observe for cancellation requests.
Returns
A collection of DocNode objects representing each processed Markdown file, containing the display title, path relative to rootPath, and generated HTML.
Remarks
Skips files in excluded directories (for example "node_modules", "bin", "obj", and "Tests") and hidden dot-prefixed directories unless explicitly allowlisted. Dot-prefixed files are included. If a file's name is "README" (case-insensitive), its title is set to the parent directory name or "Home" for a repository root README. Files that fail to process are skipped and an error is logged.
CSharpDocHarvester
Harvester implementation that scans C# source files for XML documentation comments.
HarvestAsync
Task<IReadOnlyList<DocNode>> HarvestAsync(string rootPath, CancellationToken cancellationToken = default)
Collects XML documentation from C# source files under the specified root and produces DocNode entries containing titles, relative file paths with anchors, and HTML-formatted content.
Parameters
rootPathThe root directory to recursively scan for .cs files.cancellationTokenAn optional token to observe for cancellation requests.
Returns
A collection of DocNode objects; each contains a title, a relative file path including a fragment anchor, and the extracted HTML documentation.
Remarks
Skips files in excluded directories (for example "node_modules", "bin", "obj", and "Tests") and hidden dot-prefixed directories unless explicitly allowlisted. Dot-prefixed files are included.
GetMethodId
string GetMethodId(MethodDeclarationSyntax method, string qualifiedTypeName)
Computes the safe ID for a method to be used in HTML content and stub nodes.
Parameters
methodThe method declaration syntax.qualifiedTypeNameThe qualified name of the containing type.
Returns
The safe ID string for the method documentation section.
GetPropertyId
string GetPropertyId(PropertyDeclarationSyntax property, string qualifiedTypeName)
Computes the safe ID for a property to be used in HTML content and stub nodes.
Parameters
propertyThe property declaration syntax.qualifiedTypeNameThe qualified name of the containing type.
Returns
The safe ID string for the property documentation section.
GetHighlightedDisplaySignature
string GetHighlightedDisplaySignature(MethodDeclarationSyntax method)
Generates a syntax-highlighted HTML string representing a method signature for display.
Parameters
methodThe method declaration syntax.
Returns
An HTML fragment containing the highlighted signature.
GetHighlightedPropertySignature
string GetHighlightedPropertySignature(PropertyDeclarationSyntax property)
Generates a syntax-highlighted HTML string representing a property signature for display.
Parameters
propertyThe property declaration syntax.
Returns
An HTML fragment containing the highlighted signature.
GetPropertyAccessorSignature
string GetPropertyAccessorSignature(PropertyDeclarationSyntax property)
Computes the accessors (get/set/init) for a property as a string for inclusion in signatures.
Parameters
propertyThe property declaration syntax.
Returns
A string like "{ get; set; }" or "{ get; }".
AppendHighlightedParameter
void AppendHighlightedParameter(StringBuilder builder, ParameterSyntax parameter)
Appends a syntax-highlighted parameter declaration to the provided StringBuilder.
Parameters
builderThe StringBuilder to append to.parameterThe parameter declaration syntax.
GetDisplayTypeName
string GetDisplayTypeName(TypeDeclarationSyntax typeDecl)
Gets the display name for a type declaration, including generic type parameter placeholders (e.g., <T>).
Parameters
typeDeclThe type declaration syntax.
Returns
The display name string.
GetTypeNameForQualifiedId
string GetTypeNameForQualifiedId(TypeDeclarationSyntax typeDecl)
Gets the type name for a qualified ID, appending backtick arity for generic types (e.g., MyType`1).
Parameters
typeDeclThe type declaration syntax.
Returns
The type name string used in safe IDs.
IsCompilerGeneratedCallerParameter
bool IsCompilerGeneratedCallerParameter(ParameterSyntax parameter)
Determines whether a parameter is a compiler-generated caller information parameter (e.g., [CallerFilePath]).
Parameters
parameterThe parameter declaration syntax.
Returns
true if the parameter should be hidden from documentation; otherwise, false.
ExtractDoc
string? ExtractDoc(SyntaxNode node)
Extracts XML documentation from the leading trivia of a syntax node and converts it into HTML fragments.
Parameters
nodeThe syntax node whose leading XML documentation comments will be parsed.
Returns
The HTML string containing structured documentation sections, or null if no documentation is present or parsing fails.
AppendTextSection
void AppendTextSection(StringBuilder html, string cssClass, XElement? section, string? heading = null)
Appends a simple text section (like summary or remarks) to the HTML builder.
Parameters
htmlThe StringBuilder to append to.cssClassThe CSS class name for the section container.sectionThe XElement containing the documentation section.headingOptional heading text for the section.
AppendNamedListSection
void AppendNamedListSection(StringBuilder html, string cssClass, string heading, IEnumerable<XElement> entries, Func<XElement, string?> keySelector)
Appends a list of named entries (like parameters or exceptions) to the HTML builder.
Parameters
htmlThe StringBuilder to append to.cssClassThe CSS class name for the section container.headingThe heading text for the section.entriesThe collection of XElements to process.keySelectorA function that extracts the name or key for each entry.
RenderBlockContent
string RenderBlockContent(XElement element)
Renders the content of an XElement as block-level HTML (wrapping in paragraphs if necessary).
Parameters
elementThe XElement to render.
Returns
An HTML fragment string.
RenderInlineContent
string RenderInlineContent(XElement element)
Renders the content of an XElement as inline HTML.
Parameters
elementThe XElement to render.
Returns
An HTML fragment string.
RenderNodes
string RenderNodes(IEnumerable<XNode> nodes, bool inlineContext)
Renders a collection of XML nodes into HTML strings.
Parameters
nodesThe nodes to render.inlineContextIndicates whether rendering occurs in an inline context (affects paragraph handling).
Returns
The combined HTML string.
RenderNode
string RenderNode(XNode node, bool inlineContext)
Renders a single XML node into its corresponding HTML fragment.
Parameters
nodeThe node to render.inlineContextIndicates whether rendering occurs in an inline context.
Returns
The HTML fragment string.
NormalizeWhitespace
string NormalizeWhitespace(string value)
Normalizes whitespace in the provided string by replacing all whitespace sequences with a single space.
Parameters
valueThe string to normalize.
Returns
The normalized string.
SimplifyCref
string? SimplifyCref(string? cref)
Simplifies a "cref" attribute value by removing the type prefix (e.g., "M:", "T:").
Parameters
crefThe cref value to simplify.
Returns
The simplified string, or null if the input was empty.
IsCompilerGeneratedDocParameter
bool IsCompilerGeneratedDocParameter(string? parameterName)
Determines whether a parameter name corresponds to a compiler-generated caller information parameter.
Parameters
parameterNameThe name of the parameter to check.
Returns
true if it is a compiler-generated parameter; otherwise, false.
GetOrCreateNamespacePage
NamespaceDocPage GetOrCreateNamespacePage(IDictionary<string, NamespaceDocPage> namespacePages, string namespaceName)
Gets an existing NamespaceDocPage for the specified namespace name, or creates a new one if it doesn't exist.
Parameters
namespacePagesThe dictionary of existing pages.namespaceNameThe dotted namespace name.
Returns
The retrieved or newly created page.
EnsureNamespaceHierarchy
void EnsureNamespaceHierarchy(IDictionary<string, NamespaceDocPage> namespacePages)
Builds the hierarchical structure for namespaces, ensuring parent pages exist and child links are added back into the content. Rebuilds namespacePages in place keyed by NamespaceDocPage.Path.
Parameters
namespacePagesThe dictionary containing all unique namespace pages encountered during harvesting.
GetNamespaceName
string GetNamespaceName(SyntaxNode node)
Extracts the dotted namespace name for a given syntax node by traversing its ancestors.
Parameters
nodeThe syntax node to process.
Returns
The full dotted namespace name, or "Global" if none is found.
BuildNamespaceDocPath
string BuildNamespaceDocPath(string namespaceName)
Constructs the relative documentation route path for a given namespace name.
Parameters
namespaceNameThe dotted namespace name.
Returns
The relative route path string (e.g., "Namespaces/MyNamespace").
GetNamespaceTitle
string GetNamespaceTitle(string fullNamespace)
Derives a display title for a namespace name.
Parameters
fullNamespaceThe dotted namespace name.
Returns
The display title; returns the last segment of the namespace or "Namespaces" for the root.
GetParentNamespace
string GetParentNamespace(string namespaceName)
Gets the parent namespace name for a dotted namespace string.
Parameters
namespaceNameThe dotted namespace name.
Returns
The parent namespace name, or an empty string if it is a root namespace.
GetQualifiedName
string GetQualifiedName(BaseTypeDeclarationSyntax node)
Builds the dot-delimited qualified name for a type or enum declaration, including enclosing types and namespaces.
Parameters
nodeThe type or enum declaration syntax node to compute the qualified name for.
Returns
The qualified name as a dot-delimited string containing nested type and namespace segments.
NamespaceDocPage
Represents a single documentation page for a C# namespace, accumulating content from types within it.
HarvestPathExclusions
ShouldExcludeFilePath
bool ShouldExcludeFilePath(string filePath)
Determines whether a documentation file should be excluded from harvesting based on its path segments.
Parameters
filePathThe relative file path to check.
Returns
true if the file should be excluded; otherwise, false.