Broken examples after update

[bkoelman]

Describe the bug

After update from 2.74.0 to 2.74.1, examples are broken. See json-api-dotnet/JsonApiDotNetCore#1415 (comment).

To Reproduce

1. Clone the repo at https://github.com/json-api-dotnet/JsonApiDotNetCore
2. cd docs
3. ./build-dev.ps1
4. In the browser, navigate to Getting Started > API > JsonApiOptions

Expected behavior
No broken HTML.

[yufeih]

Seems to be working just fine:

[bkoelman]

Did you try on Ubuntu?

You can see the diff by downloading and extracting the documentation artifact from https://github.com/json-api-dotnet/JsonApiDotNetCore/actions/runs/7055097802 and https://github.com/json-api-dotnet/JsonApiDotNetCore/actions/runs/7208009175.

The next screenshot shows the diff:

Here's what it looks like in Chrome:

[bkoelman]

Well, it does not render entirely correct in v2.74.0 on Windows either:

    /// <summary>
    /// Whether to use relative links for all resources. <c>false</c> by default.
    /// </summary>
    /// <example>
    /// <code><![CDATA[
    /// options.UseRelativeLinks = true;
    /// ]]></code>
    /// <code><![CDATA[
    /// {
    ///   "type": "articles",
    ///   "id": "4309",
    ///   "relationships": {
    ///      "author": {
    ///        "links": {
    ///          "self": "/api/shopping/articles/4309/relationships/author",
    ///          "related": "/api/shopping/articles/4309/author"
    ///        }
    ///      }
    ///   }
    /// }
    /// ]]></code>
    /// </example>
    bool UseRelativeLinks { get; }

[bkoelman]

This is broken even worse in v2.75.1.

What it should look like (from https://www.jsonapi.net/api/JsonApiDotNetCore.Configuration.JsonApiOptions.html, which was built using v2.74.0), except for the incorrect curly indent:

What it does look like in v2.75.1 instead:

The first red arrow is new: it copies the class/interface-level comment and puts that as documentation for bool.

The source code comments can be found at: https://github.com/json-api-dotnet/JsonApiDotNetCore/blob/master/src/JsonApiDotNetCore/Configuration/IJsonApiOptions.cs#L57-L79

The docfx output for v2.75.1 is available as a downloadable build artifact at https://github.com/json-api-dotnet/JsonApiDotNetCore/actions/runs/7633561767?pr=1440. Extract documentation.zip and edit file JsonApiDotNetCore.Configuration.JsonApiOptions.html, which contains the following HTML snippet:

  <div class="codewrapper">
    <pre><code class="lang-csharp hljs">public bool UseRelativeLinks { get; set; }</code></pre>
  </div>





  <h4 class="section">Property Value</h4>
  <dl class="parameters">
    <dt><a class="xref" href="https://learn.microsoft.com/dotnet/api/system.boolean">bool</a></dt>
    <dd>Global options that configure the behavior of JsonApiDotNetCore.</dd>
  </dl>



  <h4 class="section" id="JsonApiDotNetCore_Configuration_JsonApiOptions_UseRelativeLinks_examples">Examples</h4>
  <pre><code>        &lt;pre&gt;&lt;code class=&quot;lang-csharp&quot;&gt;options.UseRelativeLinks = true;&lt;/code&gt;&lt;/pre&gt;&lt;pre&gt;&lt;code class=&quot;lang-csharp&quot;&gt;{
</code></pre>
<p>&quot;type&quot;: &quot;articles&quot;,
&quot;id&quot;: &quot;4309&quot;,
&quot;relationships&quot;: {
&quot;author&quot;: {
&quot;links&quot;: {
&quot;self&quot;: &quot;/api/shopping/articles/4309/relationships/author&quot;,
&quot;related&quot;: &quot;/api/shopping/articles/4309/author&quot;
}
}
}
}</p>

Specifically, the part:

<pre><code>        &lt;pre&gt;&lt;code class=&quot;lang-csharp&quot;&gt;options.UseRelativeLinks = true;&lt;/code&gt;&lt;/pre&gt;&lt;pre&gt;&lt;code class=&quot;lang-csharp&quot;&gt;{
</code></pre>

explains why it's rendered incorrectly. The text inside <pre> should not be escaped.

@yufeih Can you take another look? Please let me know what else you need to reproduce this.

Environment

Google Chrome version: 120.0.6099.225 (Official Build) (64-bit)

> dotnet --info
.NET SDK:
 Version:           8.0.101
 Commit:            6eceda187b
 Workload version:  8.0.100-manifests.1c08acc9

Runtime Environment:
 OS Name:     Windows
 OS Version:  10.0.22631
 OS Platform: Windows
 RID:         win-x64
 Base Path:   C:\Program Files\dotnet\sdk\8.0.101\

.NET workloads installed:
 Workload version: 8.0.100-manifests.1c08acc9
There are no installed workloads to display.

Host:
  Version:      8.0.1
  Architecture: x64
  Commit:       bf5e279d92

.NET SDKs installed:
  8.0.101 [C:\Program Files\dotnet\sdk]

.NET runtimes installed:
  Microsoft.AspNetCore.App 6.0.26 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
  Microsoft.AspNetCore.App 8.0.1 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
  Microsoft.NETCore.App 6.0.26 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
  Microsoft.NETCore.App 8.0.1 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
  Microsoft.WindowsDesktop.App 6.0.26 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]
  Microsoft.WindowsDesktop.App 8.0.1 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]

Other architectures found:
  x86   [C:\Program Files (x86)\dotnet]
    registered at [HKLM\SOFTWARE\dotnet\Setup\InstalledVersions\x86\InstallLocation]

Environment variables:
  Not set

global.json file:
  Not found

[filzrev]

HTML escape problems seem to occur when using both examples and `' tags.

Minimum reproducible source code

namespace Examples;

public interface IJsonApiOptions
{
    /// <summary>
    /// Whether to use relative links for all resources. <c>false</c> by default.
    /// </summary>
    /// <example>
    /// <code><![CDATA[
    /// options.UseRelativeLinks = true;
    /// ]]></code>
    /// <code><![CDATA[
    /// {
    ///   "type": "articles",
    ///   "id": "4309",
    ///   "relationships": {
    ///      "author": {
    ///        "links": {
    ///          "self": "/api/shopping/articles/4309/relationships/author",
    ///          "related": "/api/shopping/articles/4309/author"
    ///        }
    ///      }
    ///   }
    /// }
    /// ]]></code>
    /// </example>
    public bool UseRelativeLinks { get; }

}

public class JsonApiOptions : IJsonApiOptions
{
    /// <inheritdoc/>
    public bool UseRelativeLinks { get; }
}

[bkoelman]

I've created a minimal repro at #9736.