.NET xref links fail to resolve in markdown unless XML comments have a cref to it

[tom-weiland]

I'm using v2.70.1 and I want to reference System.DateTime in a markdown article, so I added a <xref:System.DateTime> link, only for it to not resolve and display in plaintext as

<xref:System.DateTime>

At first I thought I must have the wrong object ID because all the references to .NET namespaces/classes/members in my API docs (cref tags in XML comments present within my code) resolve properly and the links work as expected.

However, after trying various things I noticed that if I added a <see cref="DateTime"/> tag anywhere in my code's XML comments, the <xref:System.DateTime> link in my markdown article also resolved properly. At first I thought this was a coincidence, but upon removing the cref tag, the xref link the markdown article once again stopped resolving.

My best guess is that maybe the cref reference in XML comments causes DocFX to include a reference to the System.DateTime page (which the markdown article then "piggybacks" off), while an xref tag in a markdown article doesn't trigger this same inclusion?

Is there something I can/need to do to make xref links in markdown articles resolve properly? Or is this an oversight/bug and I should create a bug report?

[paulushub]

Also reported a link issue in #9284, but it was not resolved. Consider posting an issue, maybe that might draw attention.

[tom-weiland]

Thanks for the response. I've posted issue #9480—if you could confirm that your issue is the same (do your xref links resolve properly if you add cref references for the same classes?) that would probably be helpful.

[tom-weiland]

As was explained to me by @yufeih in #9480, I was just missing

{
  "build": {
    "xref": [
      "https://learn.microsoft.com/en-us/dotnet/.xrefmap.json"
    ]
  }
}

in my DocFX config file.