Convert HTML to Markdown in C#

To convert HTML to Markdown in C#, use Converter.ConvertHTML() with an HTML source, MarkdownSaveOptions, and an output path. Aspose.HTML for .NET can produce standard Markdown, Git-style Markdown, or Markdown output limited to selected HTML features.

This guide shows the core HTML to Markdown workflows for C# applications: basic conversion, custom MarkdownSaveOptions, Git-style Markdown output, and inline HTML handling. Before running the examples, install and configure Aspose.HTML for .NET in your project. The complete C# example project is available in the Aspose.HTML for .NET GitHub repository.

Markdown is a plain-text markup format commonly used for documentation, README files, static-site content, and developer publishing workflows. HTML to Markdown conversion is useful when an application needs to migrate existing HTML content into a readable text format, prepare documentation sources, or normalize generated HTML for further editing.

Convert HTML to Markdown in C#

The static Converter class provides a direct way to convert HTML content to Markdown. The example below uses ConvertHTML() with HTML input and writes the result to a Markdown file.

// Convert HTML to Markdown in C#

// Prepare HTML code and save it to a file
string code = "<h1>Header 1</h1>" +
              "<h2>Header 2</h2>" +
              "<p>Convert HTML to Markdown</p>";
File.WriteAllText("convert.html", code);

// Call ConvertHTML() method to convert HTML to Markdown
Converter.ConvertHTML("convert.html", new MarkdownSaveOptions(), Path.Combine(OutputDir, "convert.md"));

Use this workflow when default Markdown output is enough and the source HTML does not need special filtering rules. For more controlled output, configure MarkdownSaveOptions as shown below.

Short HTML to Markdown Recipes

• Convert HTML to Markdown – call Converter.ConvertHTML() with the HTML source and output .md path.
• Convert only selected HTML elements – configure MarkdownSaveOptions.Features before conversion.
• Generate Git-style Markdown – use the predefined MarkdownSaveOptions.Git settings.
• Keep unsupported markup as HTML – use inline HTML behavior for elements that should remain unconverted.
• Convert documentation HTML to editable Markdown – use this workflow for README, docs, and static-site source migration.
• Convert Markdown back to HTML – see Convert Markdown to HTML for the reverse workflow.

Customize HTML to Markdown with MarkdownSaveOptions

Use MarkdownSaveOptions when your application needs predictable Markdown output instead of a default conversion. The most important setting is Features, which controls which HTML elements are converted into Markdown syntax.

Option	Use it to control
Default	A predefined option set compatible with default Markdown documentation.
Features	A flag set that controls which HTML elements are converted to Markdown.
Formatter	Markdown formatting style used in the generated output.
Git	A predefined option set compatible with Git-style Markdown.
ResourceHandlingOptions	Resource handling behavior during conversion.

The workflow is:

1. Load the HTML file with an HTMLDocument constructor.
2. Create a MarkdownSaveOptions instance.
3. Configure the required options, such as Features.
4. Call Converter.ConvertHTML(document, options, savePath) to write the Markdown file.

The following example processes only links and paragraphs. Other HTML elements remain unchanged in the output.

// Convert selective HTML tags to Markdown using C#

// Prepare a path for converted file saving 
string savePath = Path.Combine(OutputDir, "options-output.md");

// Prepare HTML code and save it to the file
string code = "<h1>Header 1</h1>" +
              "<h2>Header 2</h2>" +
              "<p>Hello, World!!</p>" +
              "<a href='aspose.com'>aspose</a>";
File.WriteAllText(Path.Combine(OutputDir, "options.html"), code);

// Create an instance of SaveOptions and set up the rule: 
// - only <a> and <p> elements will be converted to Markdown
MarkdownSaveOptions options = new MarkdownSaveOptions();
options.Features = MarkdownFeatures.Link | MarkdownFeatures.AutomaticParagraph;

// Call the ConvertHTML() method to convert the HTML to Markdown
Converter.ConvertHTML(Path.Combine(OutputDir, "options.html"), options, savePath);

For deeper converter settings, see Fine-Tuning Converters.

Generate Git-Style Markdown

You can define your own conversion rules or use predefined templates. For example, the Git option creates Markdown compatible with Git-style Markdown syntax.

// Convert HTML to Markdown in C# using Git syntax

// Prepare a path for converted file saving 
string savePath = Path.Combine(OutputDir, "output-git.md");

// Prepare HTML code and save it to the file
string code = "<h1>Header 1</h1>" +
              "<h2>Header 2</h2>" +
              "<p>Hello, World!!</p>";
File.WriteAllText(Path.Combine(OutputDir, "document.html"), code);

// Call ConvertHTML() method to convert HTML to Markdown
Converter.ConvertHTML(Path.Combine(OutputDir, "document.html"), MarkdownSaveOptions.Git, savePath);

Use Git-style Markdown when the output will be stored in repositories, documentation portals, or systems that support Git-flavored Markdown extensions.

Preserve Inline HTML During Conversion

Not every HTML element has a direct Markdown equivalent. Markdown processors usually allow selected HTML blocks to remain in the document and be rendered as HTML. This behavior is useful for elements that must keep their original structure.

To preserve an element as inline HTML, mark it with the markdown attribute and the inline value. The example below keeps the content of a <div> element as HTML instead of converting it to Markdown.

// Convert inline HTML elements to Markdown using C#

// Prepare a path for converted file saving 
string savePath = Path.Combine(OutputDir, "inline-html.md");

// Prepare HTML code and save it to the file
string code = "text<div markdown='inline'><code>text</code></div>";
File.WriteAllText(Path.Combine(OutputDir, "inline.html"), code);

// Call ConvertHTML() method to convert HTML to Markdown
Converter.ConvertHTML(Path.Combine(OutputDir, "inline.html"), new MarkdownSaveOptions(), savePath);

// Output file will contain: text\r\n<div markdown="inline"><code>text</code></div>

The list of elements that support inline HTML behavior depends on the Markdown processor used after conversion. The original Markdown specification and Git-style Markdown support different sets of HTML tags, so validate the generated .md file in the target publishing system.

HTML to Markdown Conversion Limitations

Markdown is intentionally lightweight, so some HTML elements cannot be represented as native Markdown syntax. Elements such as STYLE, SCRIPT, LINK, and EMBED can be discarded or preserved as HTML depending on the selected options and processor behavior.

Feature Nesting

Markdown supports many formatting features, but not every feature can be nested inside another one. For example, list elements inside table elements may not be converted to native Markdown. Each feature is a member of the MarkdownFeatures enumeration.

Parent feature	Features which can be processed inside
Header	Link, Emphasis, Strong, InlineCode, Image, Strikethrough, Video
Blockquote	Any
List	AutomaticParagraph, Link, Emphasis, Strong, InlineCode, Image, LineBreak, Strikethrough, Video, TaskList, List
Link	Emphasis, Strong, InlineCode, Image, LineBreak, Strikethrough
AutomaticParagraph	Link, Emphasis, Strong, InlineCode, Image, LineBreak, Strikethrough
Strikethrough	Link, Emphasis, Strong, InlineCode, Image, LineBreak
Table	Video, Strikethrough, Image, InlineCode, Emphasis, Strong, Link
Emphasis	Link, InlineCode, Image, LineBreak, Strikethrough, Video
Strong	Link, InlineCode, Image, LineBreak, Strikethrough, Video

Related Markdown Workflows

• Convert Markdown to HTML – convert Markdown content back to HTML.
• Convert Markdown to PDF – render Markdown as a PDF document.
• Convert Markdown to DOCX – create Word output from Markdown.
• Convert Markdown to XPS – render Markdown to XPS.
• Convert Markdown to Image – save Markdown content as image output.

Related HTML Conversion Guides

• Convert HTML to PDF – create PDF output with PdfSaveOptions.
• Convert HTML to DOCX – save HTML as a Word document with DocSaveOptions.
• Convert HTML to XPS – render HTML to XPS output.
• Convert HTML to MHTML – package HTML and resources into one archive file.
• Convert HTML to PNG – render HTML to PNG images.
• Convert HTML to JPG – render HTML to JPEG images.

Other Platforms

• Convert HTML to Markdown in Java
• Convert HTML to Markdown in Python via .NET

Try Online HTML to Markdown Conversion

Use the online HTML to MD Converter for quick manual conversion. Use Aspose.HTML for .NET when HTML to Markdown conversion must run inside a C# application, documentation pipeline, or content migration workflow.