Convert HTML to Markdown in Java

To convert HTML to Markdown in Java, prepare an HTML file, create MarkdownSaveOptions, and call Converter.convertHTML(). Use setFeatures() to select which HTML elements are converted, or MarkdownSaveOptions.getGit() for GitLab Flavored Markdown-compatible options.

Markdown is a lightweight plain-text markup syntax widely used for documentation and README files. Aspose.HTML for Java supports the reverse of the usual Markdown-to-HTML workflow by converting supported HTML elements to Markdown with convertHTML() and MarkdownSaveOptions.

Convert HTML to Markdown in Java

The following example creates conversion.html and converts it to conversion.md with the default MarkdownSaveOptions:

1. Prepare the HTML string and save it to an input file.
2. Create MarkdownSaveOptions.
3. Call Converter.convertHTML(sourcePath, options, outputPath).

// Convert HTML to Markdown in Java

// Prepare HTML code and save it to a file
String code = "<h1>Convert HTML to Markdown Using Java</h1>" +
        "<h2>How to Convert HTML to MD in Java</h2>" +
        "<p>The Aspose.HTML for Java library allows you to convert HTML to Markdown.</p>";
FileHelper.writeAllText("conversion.html", code);

// Call ConvertHTML() method to convert HTML to Markdown
Converter.convertHTML("conversion.html", new MarkdownSaveOptions(), "conversion.md");

Save Options – MarkdownSaveOptions Class

The MarkdownSaveOptions class controls which HTML elements are converted, the Markdown formatting style, resource handling, and predefined compatibility settings.

Method	Use it to
getDefault()	Get options compatible with default Markdown documentation.
setFeatures(value)	Set flags that control which HTML elements are converted to Markdown.
setFormatter(value)	Set the Markdown formatting style.
getGit()	Get options compatible with GitLab Flavored Markdown.
getResourceHandlingOptions()	Access settings for handling linked resources.

For additional save settings, see Fine-Tuning Converters. Download complete examples and data files from GitHub.

Select HTML Elements with MarkdownFeatures

The MarkdownFeatures flags control which types of HTML elements are converted to Markdown. Combine flags with the bitwise OR operator and pass the result to MarkdownSaveOptions.setFeatures().

In the following example:

1. Create an HTML file containing headings, a paragraph, and a link.
2. Create MarkdownSaveOptions.
3. Enable MarkdownFeatures.Link and MarkdownFeatures.AutomaticParagraph.
4. Call Converter.convertHTML(sourcePath, options, outputPath) to convert the HTML file to Markdown.

Only the enabled link and automatic paragraph features are selected for Markdown conversion.

In this example, the result is saved as options-output.md.

// Convert selective HTML tags to Markdown using Java

// 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>";
FileHelper.writeAllText("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.setFeatures(MarkdownFeatures.Link | MarkdownFeatures.AutomaticParagraph);

// Call the convertHTML() method to convert HTML to Markdown
Converter.convertHTML("options.html", options, "options-output.md");

Use GitLab Flavored Markdown Options

MarkdownSaveOptions.getGit() returns a predefined set of options compatible with GitLab Flavored Markdown. Use it when the output is intended for GitLab-compatible Markdown processing.

The following example creates an HTML file and converts it to output-git.md with the predefined GitLab-compatible options:

// Convert HTML to Markdown in Java using Git syntax

// Prepare HTML code and save it to a file
String code = "<h1>Header 1</h1>" +
        "<h2>Header 2</h2>" +
        "<p>Hello, World!!</p>";
FileHelper.writeAllText("document.html", code);

// Call convertHTML() method to convert HTML to Markdown
Converter.convertHTML("document.html", MarkdownSaveOptions.getGit(), "output-git.md");

HTML to Markdown Conversion Limitations

Markdown cannot represent every HTML element or reproduce CSS-driven page layout. Elements without a Markdown equivalent, including <style>, <script>, <link>, and <embed>, are discarded during conversion.

Preserve Content as Inline HTML

Markdown processors can allow raw HTML to remain in Markdown. Aspose.HTML can preserve supported elements as inline HTML when an element is marked with the markdown="inline" attribute. Support for raw HTML elements also depends on the Markdown processor that reads the resulting file.

The following example converts inline.html to inline-html.md. The <div markdown="inline"> element and its <code> child remain as HTML in the output:

// Convert inline HTML elements to Markdown using Java

// Prepare HTML code and save it to a file
String code = "text<div markdown='inline'><code>text</code></div>";
FileHelper.writeAllText("inline.html", code);

// Call convertHTML() method to convert HTML to Markdown
Converter.convertHTML("inline.html", new MarkdownSaveOptions(), "inline-html.md");

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

The original Markdown specification supports the following block-level raw HTML elements: BLOCKQUOTE, H1–H6, P, PRE, OL, UL, DL, DIV, INS, DEL, IFRAME, FIELDSET, NOSCRIPT, FORM, and MATH.

GitLab Flavored Markdown extends the supported set with elements including ARTICLE, FOOTER, NAV, ASIDE, HEADER, ADDRESS, HR, DD, FIGURE, FIGCAPTION, ABBR, VIDEO, AUDIO, OUTPUT, CANVAS, SECTION, DETAILS, HGROUP, and SUMMARY.

Feature Nesting

Not every Markdown feature can be nested inside every other feature. For example, list elements inside table elements are not converted. The following table shows the supported nesting combinations for members of the MarkdownFeatures enumeration.

Parent feature	Features that 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

• HTML Converter – choose another HTML output format.
• Markdown Converter – convert Markdown to HTML, PDF, or images.
• Convert Markdown to HTML – perform the reverse Markdown-to-HTML workflow.

Other Platforms

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

FAQ

Can I convert HTML to Markdown for free?

Yes. Use the free online HTML to Markdown Converter for a quick manual conversion. Aspose.HTML for Java is a commercial API for programmatic conversion and can be evaluated before licensing; see Licensing.

Does HTML-to-Markdown conversion preserve CSS and page layout?

No. Markdown represents document structure rather than CSS-based visual layout. Use MarkdownSaveOptions to control supported converted features, and use inline HTML where the target Markdown processor supports it.

Try Online HTML to Markdown Conversion

Use the free online HTML to Markdown Converter for quick manual conversion without writing Java code.