[Feature Request] Make <a/> tag in headers optional when outputFormat: markdown

[bohyunjung]

Describe the bug

A rendered markdown file includes an empty <a/> tag in the markdown H1 title.
For example:

# <a id="Newtonsoft_Json_Generated_CustomBinding0_4"></a> Delegate CustomBinding0<TSelf, T0, T1, T2\>

Is this rendered for a reason, or is it a bug? What is the role of this element?

To Reproduce
Steps to reproduce the behavior:

Run docfx with metadata.outputFormat: "markdown" option.

Whole docfx.json

{
  "metadata": [
    {
      "src": [
        {
          "src": "..",
          "files": [
            "**/*.cs"
          ]
        }
      ],
      "dest": "api",
      "globalNamespaceId": "Global",
      "allowCompilationErrors": true,
      "namespaceLayout": "nested",
      "outputFormat": "markdown"
    }
  ]
}

Expected behavior

If rendering this empty <a/> element is unnecessary, I expect this not to be included in the markdown file.

Context (please complete the following information):

• OS: macOS 14.2.1(23C71)
• Docfx version: 2.75.3+a5c719410037cc288c7adff010b1abf3c0f2e581
• Dotnet version: 7.0.403

Additional context

I'm working on a Unity package project, and I referenced the docfx settings of https://github.com/CaseyHofland/docfx-unitypackage.

[bohyunjung]

docfx/src/Docfx.Build/ApiPage/ApiPageMarkdownTemplate.cs

Lines 50 to 51 in 46723af

	FormattableString? ToHeading(int level, string title, string? id = null) =>
	$"{new string('#', level)}{(string.IsNullOrEmpty(id) ? null : $" <a id=\"{id}\"></a>")} {Escape(title)}\n\n";

Ah, this should be an intended anchor tag. I see.

There would be some folks like me who aim to use these generated markdowns as a source to build the final HTML... So, making it optional whether to include the anchor tags in headings (and any other stuff intended to be included in the markdown as the final product) should introduce more flexibility to the markdown output usage?

[yufeih]

The <a> tag creates a permalink and is useful to create links that points to an API on the page, in your example, an URL like <page-url>#Newtonsoft_Json_Generated_CustomBinding0_4 should link to the CustomBinding0 method instead of page top.

[bohyunjung]

Yes, I understand they act as anchor tags, as you noted.

However, when more markdown rendering options are introduced later, I think the generation of the <a> tag is worth setting optional - especially for those using the docfx-generated markdowns as the source for the final doc. (Also, I didn't expect these docfx-generated markdowns to be ready-to-service since it is metadata outputFormat)

For now, I'll set up a post-process for the trimming the output.

Thank you for introducing the markdown generation feature. 💞

[yufeih]

Looks like a legitimate request.

[bohyunjung]

Thanks.
I've changed the title to a feature request, but I don't have access to update the label.

[bohyunjung]

Update:

If the <a/> tag becomes optional, links that contain DocFX-generated anchors should adapt accordingly. In the "Inherited Members" section, DocFX creates links using its anchor expression style. The final anchor treatment depends on the converter's settings when converting DocFX-generated markdown to HTML using a tool like Docusaurus.