[Bug] .NET API / Markdown: Unresolved cref / xref tags from <summary> in generated markdown.

[Delsin-Yu]

Describe the bug

The following XML Documentation:

does not resolve when converted to markdown, this is what appears in the GitHub.

In contrast, the generated website appears to resolve the links correctly:

Docfx.json

• docfx.json config

{
	"rules": {
		"InvalidHref": "error"
	},
	"metadata": [
		{
			"src": [
				{
					"src": "GDViews.VirtualGridView",
					"files": [
						"**/*.csproj"
					]
				}
			],
			"dest": "Documentation",
			"filter": "filterConfig.yml",
			"outputFormat": "markdown",
			"disableGitFeatures": "true",
			"enumSortOrder": "declaringOrder"
		}
	]
}

Source Repo

The GDViews.VirtualGridView repo.

[filzrev]

does not resolve when converted to markdown, this is what appears in the GitHub.

Currently generated markdown files with "outputFormat": "markdown" option are intended to be used as docfx build command inputs.

So generated markdown files contains some docfx specific custom tags like <xref>.
And these custom tags are ignored by GitHub's markdown preview.

Raw view of generated file
https://raw.githubusercontent.com/Delsin-Yu/GDViews.VirtualGridView/main/Documentation/GodotViews.VirtualGrid.md

---

If there are no strict requirements for previewing the markdown file on GitHub.
Try to publish document to GitHub Pages

[Kevinf63]

@Delsin-Yu and @filzrev, I similarly ran into this with "outputFormat": "markdown". I think a good live example of this issue is visible in DocFx's own cross referencing documentation:

Not sure if it's intentional or a mistake?
https://dotnet.github.io/docfx/docs/links-and-cross-references.html#more-options-for-cross-referencing-net-api-docs

<p>
  e.g.: 
  <code>
    [](xref:System.String?title=String+Class)
  </code>
   will be resolved as 
  <a href="xref:System.String?title=String+Class"></a>.
</p>

[filzrev]

@Kevinf63
It seems xref is not resolved as expected on official docs.
(it's resolved by xrefService before but it's retired #9659)

I've created PR(#9880) to resolve xref resolver issue on conceptual documentation.

[filzrev]

It seems resolved by publishing docs to GitHub pages.
And official docs xref problems are resolved by merged PR.

@Delsin-Yu
If there is no additional problems. Please close this issue.

[Delsin-Yu]

There is a following issue when talking about resolving xrefs,, should I open a separate issue on it? Since it's not markdown-related.

https://delsin-yu.github.io/GDViews.VirtualGridView/api/GodotViews.VirtualGrid.DynamicGridViewers.html

[filzrev]

There is a following issue when talking about resolving xrefs.

It seems be caused by #9677 issue.