search

dotnet / docfx

Static site generator for .NET API documentation.
https://dotnet.github.io/docfx/
MIT License
4.06k stars 862 forks source link

[Feature Request] Create links to external documentation sites like Newtonsoft.Json #9060

Open mrw1sh opened 1 year ago

mrw1sh commented 1 year ago

Description of the problem/feature Im making a documentation page for a project and one of the parameters in a Method is a JArray object from the Newtonsoft.Json NuGet package. Normally if a type is refered to it will get linked to the microsoft docs if you click on the Text (for example a List will get linked to https://learn.microsoft.com/dotnet/api/system.collections.generic.list-1). References are also made for classes that the programms define itself, for a example a Config or a Person class.

image in this image I can click on Config sends me to another page of my docs site, I can click on List, or string, which send me to the Microsoft docs, but I cant click on JArray to send me to Newtonsofts.Json documentation.

Solution I would like: I'd like to be able to set links for types in a yaml file of some sort. For example id like to define that the class Newtonsoft.Json.JArray gets linked to https://www.newtonsoft.com/json/help/html/T_Newtonsoft_Json_Linq_JArray.htm

considered alternatives Its possible this feature exists but I can't find a tutorial in docfxs documention. I found a similar issue already on StackOverflow (https://stackoverflow.com/questions/70602507/retrieve-docfx-metadata-from-nuget-packages) but it still wouldn't link the JArray class to any sort of documentation.

Additional context I am new to docfx and haven't styled my template completly so please forgive me for it beeing a bit ugly in the screenshot

KalleOlaviNiemitalo commented 1 year ago

Cross reference map file (xrefmap) is intended for this purpose. But I don't know whether there is an xrefmap already available for Newtonsoft.Json or whether you'd have to write one yourself. The Newtonsoft.Json documentation pages are apparently generated with Sandcastle Help File Builder, and the URLs like https://www.newtonsoft.com/json/help/html/T_Newtonsoft_Json_Linq_JArray.htm are not in the same format as DocFX would use, so I don't think DocFX supports generating these URLs algorithmically without an xrefmap.