Add documentation for IMarkdownToHtmlConverter for CMS 17.2

17/umbraco-cms/SUMMARY.md

@@ -401,7 +401,7 @@
   * [Configuration](reference/developer-mcp/configuration.md)
   * [Available Tools](reference/developer-mcp/available-tools.md)
   * [Excluded Tools](reference/developer-mcp/excluded-tools.md)
-  * [Use Cases and Scenarios](reference/developer-mcp/scenarios.md)  
+  * [Use Cases and Scenarios](reference/developer-mcp/scenarios.md)
 * [API versioning and OpenAPI](reference/api-versioning-and-openapi.md)
 * [Searching](reference/searching/README.md)
   * [Examine](reference/searching/examine/README.md)
@@ -475,6 +475,7 @@
 * [Content Type Filters](reference/content-type-filters.md)
 * [Database Availability Checks](reference/database-availability.md)
 * [JSON Serialization](reference/json-serialization.md)
+* [Markdown to HTML Conversion](reference/markdown-to-html-conversion.md)
 * [Property Editor UIs](reference/property-editor-uis/README.md)
 
 ## Tutorials

17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/markdown-editor.md

@@ -47,6 +47,12 @@ There are three settings available for manipulating the **Markdown editor** prop
 | copy       | Ctrl + C |
 | paste      | Ctrl + V |
 
+## Markdown to HTML Conversion
+
+The conversion from markdown to HTML is handled by the registered implementation of `IMarkdownToHtmlConverter`.
+
+To understand this more and how you may customize it to your needs, see the article on [Markdown to HTML Conversion](../../../../reference/markdown-to-html-conversion.md).
+
 ## MVC View Example
 
 ### With Models Builder
@@ -81,8 +87,8 @@ The example below demonstrates how to add values programmatically using a Razor
 
     // Create markdown value
     var markdownValue = new HtmlString("#heading  \n**strong text**");
-    
-    // Set the value of the property with alias 'myMarkdownEditor'. 
+
+    // Set the value of the property with alias 'myMarkdownEditor'.
     content.SetValue("myMarkdownEditor", markdownValue);
 
     // Save the change
@@ -95,7 +101,7 @@ Although the use of a GUID is preferable, you can also use the numeric ID to get
 ```csharp
 @{
     // Get the page using it's id
-    var content = ContentService.GetById(1234); 
+    var content = ContentService.GetById(1234);
 }
 ```
 

17/umbraco-cms/reference/markdown-to-html-conversion.md

@@ -0,0 +1,53 @@
+---
+description: Describes how markdown to HTML is carried out within Umbraco.
+---
+
+# Markdown to HTML Conversion
+
+Umbraco requires Markdown to be converted into HTML. Primarily, this is to support the [Markdown property editor](../fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/markdown-editor.md). There are also internal use cases, for example, in rendering email notification content for [health checks](../extending/health-check/README.md).
+
+The conversion is managed via the `IMarkdownToHtmlConverter` interface.
+
+Umbraco registers a default implementation of `HeyRedMarkdownToHtmlConverter`, which is based on the [Hey Red Markdown library](https://github.com/hey-red/Markdown).
+
+Also provided is an unregistered, alternate implementation of `MarkdigMarkdownToHtmlConverter`, based on the [Markdig library](https://github.com/xoofx/markdig).
+
+Both implementations convert standard markdown into HTML, but there are some subtle differences in the output produced.
+
+## Modifying the Default Behavior
+
+If you prefer to use the Markdig-based implementation, replace the default registration by adding the following composer:
+
+```csharp
+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>();
+    }
+}
+```
+
+Alternatively, the interface itself can be implemented directly, enabling you to use the library and custom behavior you prefer:
+
+```csharp
+namespace Umbraco.Cms.Core.Strings;
+
+public interface IMarkdownToHtmlConverter
+{
+    /// <summary>
+    /// Converts the specified Markdown-formatted text to an HTML-encoded string.
+    /// </summary>
+    /// <param name="markdown">The input string containing Markdown syntax to be converted.</param>
+    /// <returns>A string containing the HTML representation of the input Markdown.</returns>
+    public string ToHtml(string markdown);
+}
+```
+
+## Planned Updates
+
+The Hey Red Markdown library is now deprecated. We expect to make the implementation based on Markdig the default one registered from Umbraco 18. The Hey Red Markdown library implementation will be removed in Umbraco 19.