[Regression] Links are no longer clickable after update to 2.78.3

[bkoelman]

Describe the bug Links in v2.78.2 were rendered as clickable links, which is no longer the case after updating to v2.78.3.

Before:

After:

Source code this was produced from:

using JetBrains.Annotations;
using Microsoft.AspNetCore.Mvc.Filters;

namespace JsonApiDotNetCore.Middleware;

/// <summary>
/// Converts action result without parameters into action result with null parameter.
/// <example>
/// <code><![CDATA[
/// return NotFound() -> return NotFound(null)
/// ]]></code>
/// </example>
/// This ensures our formatter is invoked, where we'll build a JSON:API compliant response. For details, see:
/// https://github.com/dotnet/aspnetcore/issues/16969
/// </summary>
[PublicAPI]
public interface IAsyncConvertEmptyActionResultFilter : IAsyncAlwaysRunResultFilter;

To Reproduce Steps to reproduce the behavior:

1. Clone the repo at https://github.com/json-api-dotnet/JsonApiDotNetCore
2. cd docs
3. .\build-dev.ps1 -NoBuild
4. Browser opens, navigate to http://localhost:8080/api/JsonApiDotNetCore.Middleware.IAsyncConvertEmptyActionResultFilter.html
5. dotnet tool update docfx
6. Continue from step 3 and observe change in browser

Expected behavior No change in clickable links.

Context (please complete the following information):

• OS: Windows

• Docfx version: 2.78.3

• .NET version: .NET 9 SDK v9.0.103, runtimes: 8.0.13, 9.0.2

• docfx.json config

{
  "metadata": [
    {
      "properties": {
        "ProduceReferenceAssembly": "true"
      },
      "src": [
        {
          "files": [
            "**/JsonApiDotNetCore.csproj",
            "**/JsonApiDotNetCore.Annotations.csproj"
          ],
          "src": "../"
        }
      ],
      "dest": "api",
      "disableGitFeatures": false
    }
  ],
  "build": {
    "content": [
      {
        "files": [
          "api/**.yml",
          "api/index.md",
          "getting-started/**.md",
          "getting-started/**/toc.yml",
          "usage/**.md",
          "request-examples/**.md",
          "internals/**.md",
          "toc.yml",
          "*.md"
        ],
        "exclude": [
          "**/README.md"
        ]
      }
    ],
    "resource": [
      {
        "files": [
          "diagrams/*.svg"
        ]
      }
    ],
    "overwrite": [
      {
        "exclude": [
          "obj/**",
          "_site/**"
        ]
      }
    ],
    "dest": "_site",
    "globalMetadataFiles": [],
    "fileMetadataFiles": [],
    "template": [
      "default",
      "modern"
    ],
    "postProcessors": [],
    "noLangKeyword": false,
    "keepFileLink": false,
    "cleanupCacheHistory": false,
    "disableGitFeatures": false
  }
}

• Exceptions

None

• Errors and warnings

None

• .NET info

.NET SDK:
 Version:           9.0.103
 Commit:            96da45d427
 Workload version:  9.0.100-manifests.ea610b94
 MSBuild version:   17.12.24+90b52dda6

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

.NET workloads installed:
There are no installed workloads to display.
Configured to use loose manifests when installing new manifests.

Host:
  Version:      9.0.2
  Architecture: x64
  Commit:       80aa709f5d

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

.NET runtimes installed:
  Microsoft.AspNetCore.App 8.0.13 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
  Microsoft.AspNetCore.App 9.0.2 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
  Microsoft.NETCore.App 8.0.13 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
  Microsoft.NETCore.App 9.0.2 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
  Microsoft.WindowsDesktop.App 8.0.13 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]
  Microsoft.WindowsDesktop.App 9.0.2 [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

Additional context None

[bkoelman]

@filzrev Can this be either fixed or the changes causing this issue be rolled back? We haven't been able to update due to this bug.

[bart-vmware]

Possibly related to https://github.com/SteeltoeOSS/Documentation/issues/373.

[filzrev]

Sorry for inconvenience by introducing regression.

If it's able to edit source XML comment. Try to insert empty line after </example> tag.

Background When converting XML comment to markdown and HTML. It needs to add Empty Line before/after HTML tags (It's required by Markdown specs)

I've added code to fix problem that relating above issue at v2.78.3. But it seems introducing another behavior changes.

To fix XML comment related issues. it need to refactor code. and need to add additional test cases.

@bart-vmware Is it able to provide xml text that cause issues? I'll add test cases.

[bart-vmware]

@filzrev There's no example, so may not be related to this issue. This is the source code, available here:

// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the Apache 2.0 License.
// See the LICENSE file in the project root for more information.

using Microsoft.Extensions.DependencyInjection;
using Steeltoe.Common;

namespace Steeltoe.Configuration.CloudFoundry;

/// <summary>
/// Extension methods for adding services related to CloudFoundry.
/// </summary>
public static class CloudFoundryServiceCollectionExtensions
{
    /// <summary>
    /// Registers <see cref="CloudFoundryApplicationOptions" /> and <see cref="CloudFoundryServicesOptions" /> for use with the options pattern. The first
    /// type is also registered as <see cref="IApplicationInstanceInfo" /> in the IoC container for easy access.
    /// </summary>
    /// <param name="services">
    /// The <see cref="IServiceCollection" /> to add services to.
    /// </param>
    /// <returns>
    /// The incoming <paramref name="services" /> so that additional calls can be chained.
    /// </returns>
    public static IServiceCollection AddCloudFoundryOptions(this IServiceCollection services)
    {
        throw new NotImplementedException();
    }
}

which outputs at https://steeltoe.io/api/v4/Steeltoe.Configuration.CloudFoundry.CloudFoundryServiceCollectionExtensions.html as:

[filzrev]

@bart-vmware

Thanks for providing examples. It seems <see cref="IServiceCollection" /> XML comment to
<xref href="Microsoft.Extensions.DependencyInjection.IServiceCollection" data-throw-if-not-resolved="false"></xref> tag conversion is failed with some reasons.

I've confirmed GitHub Actions CI logs] and following docfx warnings are recorded.

warning: Ignore duplicated member Method

I though above broken link issues are caused by these warnings.

[bart-vmware]

@filzrev Which logs are you referring to?

[filzrev]

@bart-vmware I've confirmed following Generate API Browser docs steps log. https://github.com/SteeltoeOSS/Documentation/actions/runs/15730888113/job/44331515051

[bart-vmware]

@filzrev I don't think that's related. All those warnings belong to v2/v3 APIs. In the past, someone thought it'd be a good idea to expose types in different assemblies with the same namespace. We fixed that in v4, which is the link I reported this problem for. I don't see any warnings for v4 in the log.

[filzrev]

@bart-vmware I've confirmed Microsoft.Extensions.DependencyInjection types are excluded by api-filter.yml setting.

If API is excluded by filterConfig. xref is rendered as plain text.

[bart-vmware]

@filzrev Awesome, thanks so much for digging that up! Without the filter, it all works properly.

[bkoelman]

Sorry for inconvenience by introducing regression.

If it's able to edit source XML comment. Try to insert empty line after </example> tag.

Background When converting XML comment to markdown and HTML. It needs to add Empty Line before/after HTML tags (It's required by Markdown specs)

I've added code to fix problem that relating above issue at v2.78.3. But it seems introducing another behavior changes.

To fix XML comment related issues. it need to refactor code. and need to add additional test cases.

@filzrev Any progress on this? We're using Resharper to auto-format the codebase, so we can't add an empty line after the </example> tag because the formatter auto-removes it.

[bkoelman]

Is there anything I can do to help move forward on this? Last time I checked, DocFX failed to run on .NET 10 RC1, so this will be a blocker for the upgrade.

[bkoelman]

@filzrev I've restructured our documentation to not be affected by this bug anymore, so it's no longer a priority.