dotnet / docfx

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

[Bug] Opening angle bracket not escaped in Markdown output #9950

Open alexeyzimarev opened 2 months ago

alexeyzimarev commented 2 months ago

Describe the bug When using docfx metadata to generate Markdown output, most of the Markdown-supported characters are properly escaped with \. However, opening angle brackets aren't escaped, which causes some static site generators to fail as they expect an HTML tag when processing opening angle brackets.

To Reproduce Use a config file similar to this, with outputFormat set to markdown:

{
    "metadata": [
        {
            "src": [{
                "files": ["*.dll"],
                "src": "./output"
              }],
            "dest": "docs/docs/api",
            "outputFormat": "markdown"
        }
    ]
}

Run docfx metadata. Inspect Markdown output.

Notice that opening angle brackets aren't escaped, whilst closing angle brackets are:

#### Implements

[IReadOnlyCollection<Parameter\>](https://learn.microsoft.com/dotnet/api/system.collections.generic.ireadonlycollection\-1), 
[IEnumerable<Parameter\>](https://learn.microsoft.com/dotnet/api/system.collections.generic.ienumerable\-1), 

Expected behavior

Output like this:

#### Implements

[IReadOnlyCollection\<Parameter\>](https://learn.microsoft.com/dotnet/api/system.collections.generic.ireadonlycollection\-1), 
[IEnumerable\<Parameter\>](https://learn.microsoft.com/dotnet/api/system.collections.generic.ienumerable\-1), 

Context:

filzrev commented 2 months ago

These appear to be the same issues reported in #9719.

However, opening angle brackets aren't escaped, which causes some static site generators to fail as they expect an HTML tag when processing opening angle brackets.

Currently markdown output format is intended to be used as input for docfx build command. And following problems are known other than #9719 when markdown files are used by other tools.