Free · Open source · Client-side

HTML to MDX

Convert HTML to clean MDX-ready Markdown

New to MDX? Read MDX vs Markdown or browse the MDX cheatsheet.

How to Convert HTML to MDX

Paste HTML into the editor and the converter produces MDX-compatible Markdown. Headings, paragraphs, lists, links, and code blocks become standard Markdown. Tables, complex nested markup, and unknown elements are preserved as raw HTML — which is valid MDX. The output is ready to paste into a Next.js, Docusaurus, or Astro MDX file.

What gets converted

Standard HTML elements with Markdown equivalents are converted: h1 through h6, p, strong, em, code, pre, a, ul, ol, li, blockquote, hr, img. Code blocks preserve language hints from class="language-*" attributes. Simple tables become Markdown tables; complex tables (with rowspan or colspan) stay as raw HTML.

Migration use cases

Use this converter when migrating content from a CMS that exports HTML — Notion, Confluence, WordPress, Ghost, or static-site exports. The output drops cleanly into any MDX-based docs platform (Next.js, Docusaurus, Astro, Gatsby) without further processing.

Why preserve raw HTML

MDX accepts raw HTML inline. When markup cannot be expressed in Markdown (complex tables, custom elements, embedded iframes), the converter leaves the original HTML in place rather than dropping data. Content survives the conversion — only executable markup is removed for safety (see below).

What is removed for safety

Executable HTML is stripped: <script> blocks, <style> blocks, and inline event handlers like onclick or onload. MDX compiles to a React component tree that runs in your app, so passing arbitrary scripts through would be an XSS footgun for anyone migrating content from a CMS. Visible content (text, links, images, structure) is always preserved.

Frequently Asked Questions

Is the HTML to MDX converter free and open source?

Yes. The HTML to MDX converter is free and open source under the Apache 2.0 license. The full source code is on GitHub at github.com/jamdesk/utilities, and there are no ads, accounts, or usage limits.

What HTML elements does it convert?

Standard elements with Markdown equivalents: headings, paragraphs, bold, italic, links, lists, code blocks, blockquotes, horizontal rules, and images. Tables convert when simple; complex tables stay as raw HTML.

Is any content dropped during conversion?

Visible content is preserved — markup that cannot be expressed in Markdown stays as raw HTML, which is valid MDX. The only things stripped are executable elements: <script> tags, <style> tags, and inline event handlers like onclick. This prevents XSS when migrating HTML into an MDX docs site.

Can I convert content from Notion or Confluence?

Yes. Export from Notion or Confluence as HTML (or copy as HTML), paste into the editor, and the output is ready for any MDX-based site.

Does it preserve syntax highlighting hints?

Yes. <code class="language-typescript"> and similar attributes are converted to fenced code blocks with the matching language tag.

About this tool

The HTML to MDX converter is free and open source. It runs entirely in your browser. Your input is never uploaded, stored, or logged — you can verify this by opening the network tab in your browser developer tools while the tool runs. The full source code is on GitHub under the Apache 2.0 license, so you can read the code, file issues, or fork the project. There are no ads, no accounts, and no usage limits. Built and maintained by Jamdesk.

Maintained by Jamdesk · Last reviewed 2026-06-12

Publish converted MDX as live docs

Jamdesk renders MDX natively — no further conversion needed. Learn more

Related Tools

↓