How to Convert HTML to Markdown and Keep Useful Links

To convert HTML to Markdown with links intact, convert the actual HTML source, then review both the visible link text and each destination URL. A normal anchor such as <a href="https://example.org/guide/">Read the guide</a> can become [Read the guide](https://example.org/guide/). Keeping that syntax correct is the first step; making sure the link still reaches the intended page after migration is the second.

The HTML to Markdown converter accepts pasted HTML or an .html or .htm file. It converts the supplied source in the browser. It is not a crawler that visits a URL and reconstructs an entire website, so choose the relevant article or documentation fragment before converting.

Begin with the content you want to keep

A saved web page can contain navigation, cookie notices, related-story panels, forms, scripts, and repeated footer links alongside the article. Converting all of that at once can create a Markdown document that is technically readable but difficult to maintain.

Keep the main heading, introductory text, meaningful sections, lists, quotations, code examples, and relevant links. Remove unrelated site navigation from a copy of the source. Preserve the original file so you can compare the result and recover information that you removed too aggressively.

Prefer semantic HTML. An <h2> identifies a section heading more clearly than a generic <div> styled with a large font. An <a href="..."> carries a real destination, while a clickable element driven entirely by JavaScript may not contain a reusable link. A converter can transform the information present in the markup; it cannot reliably infer missing navigation behavior.

Understand the basic link transformation

For example, this small HTML fragment contains a heading, a paragraph, and a link:

<h2>Review the release</h2>
<p>
  Read the <a href="https://example.org/handbook/review/">review checklist</a> before signing off.
</p>

Its Markdown equivalent can be:

## Review the release

Read the [review checklist](https://example.org/handbook/review/) before signing off.

The label remains useful when the sentence is read aloud or viewed without surrounding styling. If the original label was “click here,” consider improving it during cleanup. Conversion preserves source information; it does not automatically turn every label into good navigation text.

The CommonMark link specification describes Markdown’s separation between link text and destination. That distinction also helps when reviewing a migration: a correct-looking label can still hide a stale or incorrect URL.

Resolve relative links against the new destination

An absolute URL contains its scheme and host, such as https://example.org/handbook/. A root-relative URL such as /handbook/ uses the current site’s host. A path such as ../review/ depends on the current document’s location. These can all be valid links, but they do not have the same migration behavior.

Suppose an article moves from a company website into a Git repository. A root-relative /handbook/ link no longer necessarily points to the company handbook. It will be interpreted in the context of the new host or renderer. The HTML converter preserves the available destination; it does not know where you plan to publish the Markdown.

Classify relative links before changing them. Links to another page on the original site may need an absolute URL. Links between documents that are moving together may need new relative paths. Local image paths need a matching asset location, not just a rewritten string. Avoid prepending the old domain to every link without checking what each one represents.

Recheck heading anchors and HTML-only attributes

A fragment such as #installation points to an element identifier within a page. Markdown renderers commonly generate heading identifiers, but the exact normalization rules vary. Punctuation, duplicate headings, non-English characters, and renamed sections can change the generated anchor.

After conversion, test links to sections in the final renderer. An HTML heading with a custom id may lose that explicit identifier when it becomes plain Markdown heading syntax. If the destination platform offers a supported way to define stable anchors, use that mechanism deliberately.

Other HTML attributes may not have a direct Markdown equivalent. A link’s CSS class, tracking attribute, or target value is separate from its label and URL. Do not expect conversion to preserve the source site’s styling, click handlers, or new-tab behavior. Configure those behaviors in the destination website when they are actually needed.

Review sanitized and unsupported content

The site’s converter sanitizes the supplied HTML and omits active elements such as scripts and forms. Unsafe URL schemes are not preserved as usable destinations. If a “link” depended on script execution, identify the real destination and replace it with an ordinary supported link instead of trying to reintroduce the script.

Images also require a separate asset check. A Markdown image reference is a path or URL, not a bundled copy of the image file. Keep any required image assets and usage permissions with the document. A preview that renders a remote image may contact that image’s host, so choose local assets when that is important for the publishing workflow.

For HTML tables, compare the cell text after conversion. Layout tables, merged cells, and richly formatted cells need special attention. The converter’s table representation is intentionally simpler than a full browser layout, and links embedded in a complex table should be checked individually rather than assumed to survive unchanged.

Verify the converted document in two passes

First, read the Markdown source from top to bottom. Check the heading outline, paragraph order, list nesting, code fences, and the first and last sections. Search for leftover navigation text and empty link labels.

Second, render the result in the intended destination. The Markdown to HTML converter provides a quick structural preview, while your actual documentation platform confirms final anchor behavior and styling. Follow important internal links, test section fragments, and confirm that external references still point to the intended resources.

If the original material is a Word document rather than a web page, the Word to Markdown workflow can be a clearer starting point than saving Word’s HTML and cleaning up the extra markup. In either case, keep the original until the converted document and its links have passed review.