> For the complete documentation index, see [llms.txt](https://docs.umbraco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.umbraco.com/umbraco-cms/17.latest/extend-your-project/server-side-extensions/services/markdown-to-html-conversion.md).

# Markdown to HTML Conversion

Umbraco requires Markdown to be converted into HTML. Primarily, this is to support the [Markdown property editor](/umbraco-cms/17.latest/model-your-content/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](/umbraco-cms/17.latest/run-in-production/infrastructure-and-ops/health-check.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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.umbraco.com/umbraco-cms/17.latest/extend-your-project/server-side-extensions/services/markdown-to-html-conversion.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.