Written and tested by the MD Converter editorial team
How to Convert Markdown to HTML: Methods, Images, and CSS
Learn how Markdown becomes HTML, compare browser, editor, and Pandoc workflows, and avoid common problems with images, CSS, CMS platforms, and untrusted input.
What happens when Markdown becomes HTML
Markdown-to-HTML conversion replaces notation such as # Heading and - item with elements a browser can interpret.
# Announcement
- Date: August 17
- Audience: All users
The output is broadly equivalent to:
<h1>Announcement</h1>
<ul>
<li>Date: August 17</li>
<li>Audience: All users</li>
</ul>
A Markdown parser creates the document structure. CSS controls most of the spacing, color, and typography. When output looks broken, the cause may be a stylesheet or asset path rather than the HTML conversion itself.
Choose a conversion method
| Method | Best for | Main consideration |
|---|---|---|
| Browser converter | Quick use without installation | Privacy, output format, and external requests |
| Editor preview or extension | Reviewing output while writing | Differences between Markdown flavors |
| CLI such as Pandoc | Batch work, CI, and repeatable builds | Commands, templates, fonts, and CSS |
| Markdown library in an application | Websites and CMS integrations | Sanitization and dependency maintenance |
A browser or editor is convenient for a one-off document. A CLI fits output that must be reproduced, while a library is appropriate when conversion is part of a product. If you need an output format other than a web page or a printable document—presentation slides, for example—see How to Convert Markdown to Slide PDF with Marp.
Convert in a browser or editor
The basic sequence is similar across interfaces:
- Open a
.mdfile or paste the source. - Inspect headings, lists, tables, code, and images in preview.
- Choose a stylesheet or theme if needed.
- Save either an HTML fragment or a complete HTML document.
- Open the saved file in another browser before sharing it.
A command labeled Copy HTML may return only a fragment intended for insertion into an existing page. If the file must open by itself, confirm that the output is standalone and includes the document shell: <!doctype html>, html, head, and body. If the next step is printing the saved HTML or distributing it as a PDF, see How to Print Markdown or Save It as PDF for the full workflow.
Create a standalone document with Pandoc
If Pandoc is available, this command creates a standalone HTML document:
pandoc input.md --standalone --output output.html
Without --standalone, the output may be a fragment for embedding in another document. If you add CSS, decide whether recipients will receive that stylesheet separately or whether assets should be embedded in one file. Options can vary by version, so check the manual for the version in your build environment.
Fix missing images
This Markdown works only when the image exists at the expected path relative to the HTML file:
Moving the HTML alone changes that relationship. Choose one handoff strategy:
- Share the HTML and image folder with the same structure.
- Host the image and refer to an absolute URL.
- Embed the image as a data URL.
Embedding makes a single file easier to hand off but increases its size. Separate assets are often better for a public site because they can be cached; embedded assets can be useful for an attachment or offline package.
Fix missing or conflicting CSS
Correct HTML can still look unstyled when its stylesheet path returns 404. Use browser developer tools to check the network request. If the appearance changes only after pasting into a CMS, the site's theme may be overriding the converted styles.
Limit the scope of your rules by wrapping the converted body in a class:
<article class="markdown-body">
<!-- converted HTML -->
</article>
.markdown-body h2 {
margin-block: 2rem 0.75rem;
}
The Markdown CSS troubleshooting guide covers the diagnostic sequence in more detail.
Check the target CMS
WordPress and other CMS platforms may remove script, iframe, or selected attributes from pasted HTML. That behavior is usually a publishing restriction rather than a parser failure.
- Use a block intended for raw or custom HTML.
- Compare the source before and after saving.
- Confirm whether inline styles are allowed.
- Preview on desktop and mobile before publishing.
For recurring publishing, a supported Markdown feature or official CMS API may be easier to maintain than repeated manual pasting.
Do not publish untrusted Markdown without sanitizing it
Some Markdown parsers preserve raw HTML from the source. If another person can supply that source, the generated page may contain unsafe elements or URLs.
For untrusted input, disable raw HTML where possible, allow only necessary tags and attributes, and pass the generated HTML through a maintained sanitizer. A Content Security Policy adds another layer, but a correct-looking preview is not evidence that the HTML is safe.
FAQ
Why does a .md file appear as plain text in my browser?
Most browsers do not render Markdown as a webpage by themselves. Convert it with a Markdown parser, then open the resulting HTML.
Can I edit the generated HTML directly?
Yes, but those edits do not flow back into the Markdown source. Keep the .md file as the source of truth when the document will be updated and regenerated.
Is a missing line break a conversion bug?
Not necessarily. Blank lines normally separate paragraphs, while handling of a single newline depends on the Markdown flavor and settings. See why Markdown line breaks do not show for the relevant syntax.
Summary
A useful conversion workflow covers more than the parser. Confirm whether the output is a fragment or a standalone document, decide how CSS and images travel with it, and test the rules of the destination CMS. Start with a short file and open the result in its real publishing or sharing environment before converting a long document.
ToolMarkdown to HTML (md to html)Preview .md in the browser, adjust layout, and download HTML.Open tool