Convert HTML to Markdown in Python

To convert HTML to Markdown in Python, pass an HTML file, HTMLDocument, or Url to Converter.convert_html() with MarkdownSaveOptions and an output path. Use MarkdownSaveOptions.default for standard Markdown or MarkdownSaveOptions.git for GitLab Flavored Markdown-compatible output.

HTML-to-Markdown conversion preserves supported document structure, such as headings, paragraphs, links, lists, emphasis, and code. It does not reproduce CSS-driven appearance or page layout. Elements without an equivalent Markdown representation can remain as raw HTML or be omitted.

Convert HTML to Markdown in Python

1. Provide the HTML source as a file path, an HTMLDocument, or a Url.
2. Choose the standard or GitLab preset, or create MarkdownSaveOptions for custom conversion rules.
3. Pass the source, options, and output path to Converter.convert_html().
4. Keep any generated resource files with the Markdown output, or configure resources to be embedded.

Convert an HTML File to Markdown

To convert a local HTML file, specify the source and output paths, select a Markdown preset, and call Converter.convert_html():

import os
import aspose.html.converters as conv
import aspose.html.saving as sav

input_path = os.path.join("data", "document.html")
output_dir = "output"
os.makedirs(output_dir, exist_ok=True)
output_path = os.path.join(output_dir, "document.md")

conv.Converter.convert_html(
    input_path,
    sav.MarkdownSaveOptions.default,
    output_path
)

The standard preset converts common structures such as headings, paragraphs, lists, links, images, emphasis, blockquotes, and code.

Convert an HTML String to Markdown

The HTMLDocument constructor for an HTML string also accepts a base URI. It is the location used to resolve relative links and resource paths. The following self-contained example uses the current working directory instead of an unrelated placeholder website:

import os
import aspose.html as ah
import aspose.html.converters as conv
import aspose.html.saving as sav

output_dir = "output"
os.makedirs(output_dir, exist_ok=True)
output_path = os.path.join(output_dir, "release-notes.md")

html = """
<h1>Release Notes</h1>
<table>
  <tr><th>Version</th><th>Status</th></tr>
  <tr><td>2.0</td><td>Current</td></tr>
</table>
<p><del>Obsolete option</del></p>
"""

base_uri = os.getcwd() + os.sep

with ah.HTMLDocument(html, base_uri) as document:
    conv.Converter.convert_html(
        document,
        sav.MarkdownSaveOptions.git,
        output_path
    )

Here, base_uri points to the current directory. If the HTML contains relative resources, replace it with the directory or webpage URL against which those references should be resolved. The GitLab preset converts the table to pipe-table syntax and <del> to ~~strikethrough~~.

Convert a Webpage URL to Markdown

Use a Url object to load an online page and convert its supported content:

import os
import aspose.html as ah
import aspose.html.converters as conv
import aspose.html.saving as sav

output_dir = "output"
os.makedirs(output_dir, exist_ok=True)
output_path = os.path.join(output_dir, "aspose-from-url.md")

url = ah.Url("https://docs.aspose.com/html/files/aspose.html")
conv.Converter.convert_html(
    url,
    sav.MarkdownSaveOptions.git,
    output_path
)

The application must have network access to the page and its linked resources. Markup without native Markdown syntax, such as some containers or SVG content, can remain as raw HTML.

Standard Markdown vs. GitLab Flavored Markdown

The predefined option sets support different Markdown capabilities:

Option set	Use it for	Important behavior
MarkdownSaveOptions.default	Standard Markdown documents	Converts core structures such as headings, paragraphs, lists, links, images, emphasis, blockquotes, and code. Tables and strikethrough can remain as raw HTML.
MarkdownSaveOptions.git	GitLab Flavored Markdown	Enables extended features such as Markdown tables, strikethrough, and task lists and applies the Git formatter.

The formatter property controls the formatting style, while features determines which element types are converted. Use the git preset when both the Git formatter and its compatible feature set are required.

Configure Markdown Output

For custom conversion rules, MarkdownSaveOptions controls the feature set, formatting style, and related resources.

Option	Use it to control
features	HTML element types converted to Markdown syntax.
formatter	Markdown formatting style, such as DEFAULT or GIT.
resource_handling_options	Handling of related resources such as images.

Select HTML Elements with MarkdownFeatures

Combine MarkdownFeatures flags with the bitwise OR operator when only selected element types should be converted:

import os
import aspose.html.converters as conv
import aspose.html.saving as sav

input_path = os.path.join("data", "document.html")
output_dir = "output"
os.makedirs(output_dir, exist_ok=True)
output_path = os.path.join(output_dir, "selected-features.md")

options = sav.MarkdownSaveOptions()
options.features = (
    sav.MarkdownFeatures.LINK
    | sav.MarkdownFeatures.AUTOMATIC_PARAGRAPH
)

conv.Converter.convert_html(input_path, options, output_path)

Only links and automatic paragraphs are converted to Markdown syntax. Other elements can remain as raw HTML; disabling a feature does not necessarily remove its content.

Preserve Links and Images

With the corresponding features enabled, links become [text](URL) and images become ![alt text](path). Local images can be saved to a companion resource directory. To embed them as data URIs, create the options and set the resource-handling rule before conversion:

import aspose.html.saving as sav

options = sav.MarkdownSaveOptions.git
options.resource_handling_options.default = sav.ResourceHandling.EMBED

Embedding creates a self-contained Markdown file but increases its size, and the target Markdown renderer must allow data-URI images.

Inline HTML

Markdown processors can allow raw HTML in a Markdown document. To keep a supported element as HTML during conversion, mark it with markdown="inline", for example:

<div markdown="inline"><code>keep_html()</code></div>

The marked <div> remains HTML instead of being converted to Markdown syntax. Raw HTML support and rendering also depend on the Markdown processor that reads the generated file.

HTML to Markdown Limitations

Markdown preserves content structure rather than HTML presentation:

HTML content	Conversion behavior
Headings, paragraphs, emphasis, lists, links, images, blockquotes, and code	Converted when the corresponding features are enabled.
Tables, strikethrough, and task lists	Converted by compatible extended features, including the GitLab preset.
Containers, SVG, and elements without a Markdown equivalent	Can remain as raw HTML.
<style>, <script>, <link>, and <embed>	Do not produce equivalent Markdown syntax and can be omitted.
CSS formatting and page layout	Not preserved.

Feature Nesting

Not every Markdown feature can be nested inside every other feature. For example, list elements inside table elements are not converted to native Markdown. The following combinations are supported for members of MarkdownFeatures:

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

Common HTML to Markdown Conversion Issues

Problem	Check or fix
A table remains as HTML	Use MarkdownSaveOptions.git or a compatible table feature and formatter.
Some elements remain as raw HTML	Enable the required feature or verify that the target renderer accepts raw HTML.
CSS styling is missing	Markdown does not preserve CSS-driven appearance or page layout.
Image references are broken	Supply a valid source location or base URI and keep the generated resource directory, or use ResourceHandling.EMBED.

Related Markdown Workflows

• Markdown Converter – convert Markdown to HTML, PDF, DOCX, or images.
• Convert Markdown to HTML – perform the reverse workflow.
• Fine-Tuning Converters – configure conversion and rendering workflows.

Other Platforms

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

FAQ

Can I convert an HTML string to Markdown?

Yes. Create an HTMLDocument from the string and a meaningful base URI, then pass it to Converter.convert_html(). The base URI resolves relative links and resources.

Does HTML-to-Markdown conversion preserve tables and CSS?

Use MarkdownSaveOptions.git for compatible Markdown tables. CSS and page layout are not preserved because Markdown has no equivalent presentation model.

Can I convert HTML to Markdown for free?

Use the free online converter below for occasional manual conversion. For programmatic conversion, evaluate the library or follow the licensing guide to request a temporary license.

Try Online HTML to Markdown Conversion

Use the free online HTML to Markdown Converter for quick manual conversion without writing code. Use Aspose.HTML for Python via .NET when HTML-to-Markdown conversion must run in a Python application, documentation pipeline, or content-migration workflow.