Navigation Node Types

public interface INavigationItem
{
    /// <summary>The URL for this navigation item</summary>
    string Url { get; }

    /// <summary>Title displayed in navigation</summary>
    string NavigationTitle { get; }

    /// <summary>Root of the navigation tree</summary>
    IRootNavigationItem<INavigationModel, INavigationItem> NavigationRoot { get; }

    /// <summary>Parent in the tree, null for roots</summary>
    INodeNavigationItem<INavigationModel, INavigationItem>? Parent { get; set; }

    /// <summary>Whether this item is hidden from navigation</summary>
    bool Hidden { get; }

    /// <summary>Breadth-first index in the tree</summary>
    int NavigationIndex { get; set; }
}
		

public string Url
{
    get
    {
        var rootUrl = _homeAccessor.HomeProvider.PathPrefix.TrimEnd('/');
        var relativePath = DetermineRelativePath();

        // Remove .md extension
        var path = relativePath.EndsWith(".md") ? relativePath[..^3] : relativePath;

        // Handle index files
        if (path.EndsWith("/index"))
            path = path[..^6];
        else if (path.Equals("index"))
            return string.IsNullOrEmpty(rootUrl) ? "/" : $"{rootUrl}/";

        return $"{rootUrl}/{path.TrimEnd('/')}/";
    }
}
		

public FileNavigationLeaf(
    TModel model,
    IFileInfo fileInfo,
    FileNavigationArgs args)
		

public CrossLinkNavigationLeaf(
    CrossLinkModel model,
    string url,
    bool hidden,
    INodeNavigationItem<...>? parent,
    INavigationHomeAccessor homeAccessor)
		

new CrossLinkNavigationLeaf(
    new CrossLinkModel(new Uri("https://elastic.co"), "Elastic Docs"),
    "https://elastic.co",
    hidden: false,
    parent: this,
    homeAccessor: this
)
// URL: https://elastic.co
// NavigationTitle: "Elastic Docs"
		

public class FolderNavigation<TModel>
{
    public string FolderPath { get; }
    public ILeafNavigationItem<TModel> Index { get; }
    public IReadOnlyCollection<INavigationItem> NavigationItems { get; }
}
		

public string Url => Index.Url;
		

public class VirtualFileNavigation<TModel>
{
    public ILeafNavigationItem<TModel> Index { get; }
    public IReadOnlyCollection<INavigationItem> NavigationItems { get; }
}
		

public class DocumentationSetNavigation<TModel>
    : IRootNavigationItem<TModel, INavigationItem>
    , INavigationHomeProvider
    , INavigationHomeAccessor
{
    public Uri Identifier { get; }  // e.g., elastic-docs://
    public string PathPrefix { get; }
    public GitCheckoutInformation Git { get; }
    public INavigationHomeProvider HomeProvider { get; set; }

    public ILeafNavigationItem<TModel> Index { get; }
    public IReadOnlyCollection<INavigationItem> NavigationItems { get; }
    public bool IsUsingNavigationDropdown { get; }
}
		

// In isolated builds, it's its own home provider
DocumentationSetNavigation
{
    NavigationRoot = this,
    HomeProvider = this,
    PathPrefix = "",
    Identifier = new Uri("elastic-docs://")
}
// Child URL: /api/rest/
		

// In assembler builds, re-homed to site navigation
DocumentationSetNavigation
{
    NavigationRoot = SiteNavigation,
    HomeProvider = new NavigationHomeProvider(
        pathPrefix: "/guide",
        navigationRoot: SiteNavigation
    ),
    PathPrefix = "/guide",
    Identifier = new Uri("elastic-docs://")
}
// Child URL: /guide/api/rest/
		

// This is all it takes!
docsetNav.HomeProvider = new NavigationHomeProvider("/guide", siteNav);
		

public class TableOfContentsNavigation<TModel>
    : IRootNavigationItem<TModel, INavigationItem>
    , INavigationHomeProvider
    , INavigationHomeAccessor
{
    public Uri Identifier { get; }  // e.g., elastic-docs://api
    public string ParentPath { get; }
    public string PathPrefix { get; }
    public IDirectoryInfo TableOfContentsDirectory { get; }
    public INavigationHomeProvider HomeProvider { get; set; }

    public ILeafNavigationItem<TModel> Index { get; }
    public IReadOnlyCollection<INavigationItem> NavigationItems { get; }
}
		

// TOCs can be re-homed independently from their parent docset!
tocNav.HomeProvider = new NavigationHomeProvider("/reference", siteNav);
		

public class SiteNavigation
    : IRootNavigationItem<IDocumentationFile, INavigationItem>
{
    public Uri Identifier { get; } = new Uri("site://");
    public string Url { get; }  // Site prefix or "/"

    // All docset/TOC nodes indexed by identifier
    public IReadOnlyDictionary<Uri, IRootNavigationItem<...>> Nodes { get; }

    // Top-level navigation items
    public ILeafNavigationItem<IDocumentationFile> Index { get; }
    public IReadOnlyCollection<INavigationItem> NavigationItems { get; }

    // Phantom tracking
    public IReadOnlyCollection<PhantomRegistration> Phantoms { get; }
    public HashSet<Uri> DeclaredPhantoms { get; }
    public ImmutableHashSet<Uri> DeclaredTableOfContents { get; }
}
		

SiteNavigation
{
    Identifier = new Uri("site://"),
    NavigationRoot = this,
    Nodes = {
        [new Uri("elastic-docs://")] = DocumentationSetNavigation { ... },
        [new Uri("elastic-docs://api")] = TableOfContentsNavigation { ... },
    },
    NavigationItems = [
        DocumentationSetNavigation (re-homed to /guide),
        TableOfContentsNavigation (re-homed to /reference)
    ]
}
		

// From SiteNavigation.cs:211
private INavigationItem? CreateSiteTableOfContentsNavigation(...)
{
    var pathPrefix = $"{_sitePrefix}/{tocRef.PathPrefix}".Trim('/');

    // Look up the node
    if (!_nodes.TryGetValue(tocRef.Source, out var node))
        return null;

    // Re-home it!
    homeAccessor.HomeProvider = new NavigationHomeProvider(pathPrefix, root);

    // All URLs in subtree now use pathPrefix!
    return node;
}
		

public static class DocumentationNavigationFactory
{
    // Create a file leaf
    public static ILeafNavigationItem<TModel> CreateFileNavigationLeaf<TModel>(
        TModel model,
        IFileInfo fileInfo,
        FileNavigationArgs args)
        where TModel : IDocumentationFile
        => new FileNavigationLeaf<TModel>(model, fileInfo, args)
           { NavigationIndex = args.NavigationIndex };

    // Create a virtual file node
    public static VirtualFileNavigation<TModel> CreateVirtualFileNavigation<TModel>(
        TModel model,
        IFileInfo fileInfo,
        VirtualFileNavigationArgs args)
        where TModel : IDocumentationFile
        => new(model, fileInfo, args)
           { NavigationIndex = args.NavigationIndex };
}
		

public interface IDocumentationFile : INavigationModel
{
    string NavigationTitle { get; }
}
		

public record CrossLinkModel(Uri CrossLinkUri, string NavigationTitle)
    : IDocumentationFile;
		

public record SiteNavigationNoIndexFile(string NavigationTitle)
    : IDocumentationFile;
		

public record ApiDocumentationFile(
    string NavigationTitle,
    string ApiVersion,
    ApiType Type
) : IDocumentationFile;

// Use with generic navigation
var navigation = new DocumentationSetNavigation<ApiDocumentationFile>(
    docset,
    context,
    new ApiDocumentationFileFactory()
);