Markdown Conversion: Remove hard dependency on deprecated library and replace with IMarkdownToHtmlConverter abstraction (closes #21238 and #19500)

[AndyButland]

Prerequisites

Addresses #21238 and #19500.

Follows-up on this closed PR: #19501

Description

The first issue raises a specific concern about the detail of code block conversion to HTML, whereas the second is a more general one about our use of a deprecated library.

Given we need to ensure backward compatibility for Umbraco 17, we can't simply swap the library we use - we need to ensure the library is still available in case anyone is using it directly in projects or packages, and there may be subtle differences in the output people are relying on for styling.

So instead I've introduced an abstraction, and created implementations for both the deprecated library and it's recommended successor. The first is registered as default so existing behaviour isn't changed. But implementors can swap for the other, or provided their own with further customisations as needed.

I've then made sure to use the abstraction in each place where we are currently doing markdown to HTML conversion: in the markdown property value converter, and for a feature with health check notifications.

Change Summary

• Add IMarkdownToHtmlConverter interface in Umbraco.Core.Strings namespace for converting Markdown to HTML
• Add MarkdigMarkdownToHtmlConverter using the Markdig library (new recommended implementation)
• Add HeyRedMarkdownToHtmlConverter using HeyRed.MarkdownSharp (deprecated, but still the default until Umbraco 18 and provided for backwards compatibility until 19)
• Update HealthChecks.MarkdownToHtmlConverter to use the new abstraction with constructor injection
• Update MarkdownEditorValueConverter to use the new abstraction
• Add unit tests for both markdown converter implementations (Markdig and HeyRed)
• Add unit tests for HealthChecks.MarkdownToHtmlConverter verifying syntax highlighting for Success/Warning/Error statuses

Testing

To test verify that a markdown property editor renders the expected output.

Using a composer, register the other implementation and verify the same:

using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.Strings;
using Umbraco.Cms.Infrastructure.Strings;

public class MarkdownToHtmlComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        builder.Services.AddUnique<IMarkdownToHtmlConverter, MarkdigMarkdownToHtmlConverter>();
    }
}

The HTML should be almost or exactly the same. The only known difference I've seen is the syntax used for code blocks, but there may be other subtle differences.

Documentation

Should create a documentation page for the IMarkdownToHtmlConverter interface and the HeyRedMarkdownToHtmlConverter and MarkdigMarkdownToHtmlConverter implementations).

[Copilot]

Pull request overview

This PR introduces a new abstraction IMarkdownToHtmlConverter for converting Markdown to HTML, with two implementations: the new recommended MarkdigMarkdownToHtmlConverter using the Markdig library, and the deprecated HeyRedMarkdownToHtmlConverter for backwards compatibility. The existing code is refactored to use dependency injection with the new abstraction, maintaining backwards compatibility through obsolete constructors.

Key Changes

• Added IMarkdownToHtmlConverter interface in the Umbraco.Core.Strings namespace with two implementations (Markdig and HeyRed)
• Refactored MarkdownEditorValueConverter and HealthChecks.MarkdownToHtmlConverter to use constructor injection with the new abstraction
• Comprehensive unit tests added covering both markdown converter implementations and health check color highlighting

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/Umbraco.Core/Strings/IMarkdownToHtmlConverter.cs	New interface defining markdown-to-HTML conversion contract
src/Umbraco.Infrastructure/Strings/MarkdigMarkdownToHtmlConverter.cs	New implementation using Markdig library (recommended)
src/Umbraco.Infrastructure/Strings/HeyRedMarkdownToHtmlConverter.cs	Deprecated implementation using HeyRed.MarkdownSharp for backwards compatibility
src/Umbraco.Infrastructure/PropertyEditors/ValueConverters/MarkdownEditorValueConverter.cs	Updated to use injected converter with obsolete constructor for compatibility
src/Umbraco.Infrastructure/HealthChecks/MarkdownToHtmlConverter.cs	Updated to use injected converter with obsolete constructor for compatibility
src/Umbraco.Infrastructure/DependencyInjection/UmbracoBuilder.Services.cs	Registers HeyRed implementation as default (temporary, to be changed in V18)
src/Umbraco.Infrastructure/DependencyInjection/UmbracoBuilder.CoreServices.cs	Updates registration to use fully qualified type name to avoid conflicts
src/Umbraco.Core/Composing/TypeFinder.cs	Adds Markdig to exclusion list for type scanning
src/Umbraco.Infrastructure/Umbraco.Infrastructure.csproj	Adds Markdig package reference
Directory.Packages.props	Adds Markdig version 0.44.0
NOTICES.txt	Adds Markdig license attribution
tests/Umbraco.Tests.UnitTests/Umbraco.Infrastructure/Strings/MarkdownToHtmlConverterTests.cs	Unit tests for both markdown converter implementations
tests/Umbraco.Tests.UnitTests/Umbraco.Infrastructure/HealthChecks/MarkdownToHtmlConverterTests.cs	Unit tests for health check converter with color highlighting validation
tests/Umbraco.Tests.UnitTests/Umbraco.Core/DeliveryApi/MarkdownEditorValueConverterTests.cs	Updated test to inject deprecated HeyRed converter

[lauraneto]

Looks good! 🙌

[AndyButland]

Thanks for the review @lauraneto. I've made the suggested update and created a docs PR for the feature here: umbraco/UmbracoDocs#7740