[Bug] Failed to use xrefmap.json zip archived file

[filzrev]

Describe the bug
A clear and concise description of what the bug is.

To Reproduce
Steps to reproduce the behavior:

1. Add xref config to use zip archived xrefmap.

build:{
    "xref": [
      "xrefmap.zip"
    ]
}

2. Download xrefmap.json with following command.
   docfx download -x https://learn.microsoft.com/en-us/dotnet/.xrefmap.json xrefmap.zip
3. Run docfx build command
4. Then, following error reported.

AggregateException: One or more errors occurred. (Major map not found.)
     ArgumentException: Major map not found.
       at ctor(string majorName, HashSet<string> mapNames) in XRefRedirectionReader.cs:19
       at ctor(XRefArchive archive) in XRefArchiveReader.cs:18
       at IXRefContainerReader GetReader() in XRefArchive.cs:306
       at XRefSpec Find(string uid) in XRefRedirectionReader.cs:45
       at List<string> ResolveByXRefMaps(List<string> uidList, ConcurrentDictionary<string, XRefSpec> externalXRefSpec)
          in DocumentBuildContext.cs:256
       at void ResolveExternalXRefSpecForNoneSpecsAsync() in DocumentBuildContext.cs:203
       at void RunFromThreadPoolDispatchLoop(Thread threadPoolThread, ExecutionContext executionContext, ContextCallback
          callback, object state)
       at void RunFromThreadPoolDispatchLoop(Thread threadPoolThread, ExecutionContext executionContext, ContextCallback
          callback, object state)
       at void ExecuteWithThreadLocal(ref Task currentTaskSlot, Thread threadPoolThread)

It seems XRefArchive class expecting xrefmap.yml name only.
And don't support xrefmap.json format.

docfx/src/Docfx.Build/XRefMaps/XRefArchive.cs

Line 14 in 27da553

public const string MajorFileName = "xrefmap.yml";

Expected behavior
It can successfully handle xrefmap.json that is archived by ZIP.

Context (please complete the following information):

• OS: Windows
• Docfx version: 2.74.1

Additional context
Is there xrefmap.yml file download URL.
That is equivalent to https://learn.microsoft.com/en-us/dotnet/.xrefmap.json ?

[NattyXO]

The error you're encountering with DocFX seems related to the expectation of a specific filename ("xrefmap.yml") when utilizing the xrefmap in a zip archive. DocFX's current implementation might not be compatible with the xrefmap in JSON format archived as a zip file.

To address this:

1. Format of xrefmap:
   Currently, it seems that DocFX expects the xrefmap file to be in YAML format with the name "xrefmap.yml". This might be a limitation in the current implementation of DocFX, which doesn't support xrefmap in JSON format when using it within a zip archive.

2. Alternative Approach:
   As a workaround, you might need to generate or convert the xrefmap to YAML format and name it "xrefmap.yml". This way, it aligns with DocFX's current expectations. Tools or scripts to convert JSON to YAML might be helpful in achieving this conversion.

3. Equivalent xrefmap.yml URL:
   Regarding an equivalent xrefmap.yml file URL for "https://learn.microsoft.com/en-us/dotnet/.xrefmap.json", it might not have an exact equivalent as xrefmap files could be specific to the structure and content of a particular documentation set.

For downloading the xrefmap.yml file, it might not exist as a direct replacement for the JSON file you mentioned. The xrefmap might be generated by specific tools or processes within a documentation system.

Given the limitation you've encountered with DocFX's handling of xrefmap, you might want to consider:

• Checking for any updates or releases in the DocFX repository that might address this limitation.
• Reaching out to the DocFX community or raising an issue in their repository to get insights or potential workarounds from developers who have encountered a similar situation.

For a seamless integration, it's ideal for the tool to support xrefmap in various formats, including JSON, when archived as a zip file. However, until this is supported in DocFX, converting the JSON xrefmap to YAML or exploring alternative solutions might be necessary.

[filzrev]

Is there xrefmap.yml file download URL.
That is equivalent to https://learn.microsoft.com/en-us/dotnet/.xrefmap.json ?

I've confirmed xrefmap YAML version can be downloadable from following URL (It need to remove heading dot from file name).
https://learn.microsoft.com/en-us/dotnet/xrefmap.yml

And it can download YAML as zip with following command.

docfx download -x https://learn.microsoft.com/en-us/dotnet/xrefmap.yml xrefmap.zip