Docfx API Reference - does not resolve see tag

Question

I followed this tutorial to create a API documentation for a class library.

In the comments of my class library I us the see tag to reference other types.
For example, this is the comment of a class containing extension methods for System.Action:

/// <summary>
///     Class containing some extension methods for <see cref="Action" />.
/// </summary>
public static partial class ActionEx

docfx creates the following YAML source for the comment above:

summary: "\n    Class containing some extension methods for <xref href=\"System.Action\" data-throw-if-not-resolved=\"false\"></xref>.\n"

The final HTML output contains the same string:

Class containing some extension methods for <xref href="System.Action" data-throw-if-not-resolved="false"></xref>.

I would have docfx expected to either create a reference to System.Action or ignore the tag.

How can I make docfx to render the tag “correctly”?

Answer 1

Refer to Cross reference .NET BCL types:

When creating documentation for your own .NET library, it is needed to link to the types in .NET base class library. The .NET Framework reference documentation is not generated by DocFX, so we created a cross reference map for you so that you can use it in your project to reference .NET BCL types.

Take DocFX's own documentation as example. You can find it use xref property in docfx.json to specify the MSDN External Reference:

"xref": [
  "../src/nuspec/msdn.4.5.2/content/msdn.4.5.2.zip"
],