Markdown to HTML: How to Convert .md Files to HTML

How Markdown Becomes HTML

Markdown is a shorthand for HTML. A converter reads your .md file, recognizes each piece of syntax, and writes out the matching HTML tag. Headings become <h1>–<h6>, paragraphs become <p>, and **bold** becomes <strong>. The output is plain, unstyled HTML you can drop into any web page.

| Markdown               | HTML output                          |
|------------------------|--------------------------------------|
| # Heading              | <h1>Heading</h1>                |
| **bold**               | <strong>bold</strong>          |
| *italic*               | <em>italic</em>                |
| [link](url)            | <a href="url">link</a>         |
| `code`                 | <code>code</code>              |
| - item                 | <ul><li>item</li></ul>   |

A full document converts the same way. Here is a short Markdown file and the HTML a converter produces from it:

# Hello

This is **Markdown**.

- One
- Two

<!-- converts to -->

<h1>Hello</h1>
<p>This is <strong>Markdown</strong>.</p>
<ul>
<li>One</li>
<li>Two</li>
</ul>

The five methods below all do this same job. They differ in how much control you get and how much setup they need.

Method 1: Online Converters

The quickest option for a one-off conversion. Paste Markdown into the left pane, see the result on the right, and copy the HTML. Nothing to install.

• MDViewer Online Viewer — paste Markdown at getmd.ma/viewer/ and see it rendered as HTML instantly, with tables, code blocks, and task lists.
• Dillinger — a browser-based Markdown editor with live preview and HTML export.
• StackEdit — an in-browser editor with live preview that can export your document as HTML.
• markdown-it demo — the official demo for the markdown-it library, showing both the rendered result and the raw HTML source.

Online tools are best for short snippets. For large files, repeated conversions, or anything sensitive, a command-line tool or library keeps the work on your machine and can be automated.

Method 2: VS Code

VS Code previews Markdown out of the box. Open a .md file and press Ctrl+Shift+V (Cmd+Shift+V on Mac) to open the rendered preview. This shows you the result but does not write an HTML file.

To get an actual .html file, install the Markdown All in One extension, then:

1. Open your Markdown file.
2. Press Ctrl+Shift+P (Cmd+Shift+P on Mac) to open the Command Palette.
3. Run Markdown All in One: Print current document to HTML.

The extension saves an HTML file next to your Markdown file. It is a good choice if you already write in VS Code and only convert occasionally.

Method 3: Command Line

Command-line converters are ideal for batch jobs, build scripts, and CI pipelines.

Pandoc

Pandoc is the most versatile converter. The simplest call turns a Markdown file into an HTML fragment:

pandoc input.md -o output.html

Add -s to produce a complete, standalone HTML page (with <html> and <head>), and -c to link a stylesheet. Use -f gfm to read GitHub Flavored Markdown.

# Standalone page with a stylesheet
pandoc input.md -s -c style.css -o output.html

# Read GitHub Flavored Markdown
pandoc -f gfm input.md -o output.html

# Convert every .md file in a folder
for f in *.md; do pandoc "$f" -s -o "${f%.md}.html"; done

marked and markdown-it CLIs

If you have Node.js installed, you can run JavaScript converters without writing any code:

# marked
npx marked -i input.md -o output.html

# markdown-it
npx markdown-it input.md -o output.html

Both produce an HTML fragment, not a full page, so wrap the output in your own template if you need one.

Method 4: Programming Libraries

When Markdown conversion is part of an application — a blog, a documentation site, a comment system — use a library. Every major language has one.

JavaScript

The most common libraries are marked, markdown-it, and remark (part of the unified ecosystem, with a large plugin catalog).

// marked
import { marked } from 'marked';
const html = marked.parse('# Hello **world**');

// markdown-it
import markdownit from 'markdown-it';
const md = markdownit();
const html2 = md.render('# Hello **world**');

// remark
import { unified } from 'unified';
import remarkParse from 'remark-parse';
import remarkRehype from 'remark-rehype';
import rehypeStringify from 'rehype-stringify';

const file = await unified()
  .use(remarkParse)
  .use(remarkRehype)
  .use(rehypeStringify)
  .process('# Hello **world**');
console.log(String(file));

Python

Python has Markdown (Python-Markdown), mistune, and commonmark. Python-Markdown supports extensions for tables and fenced code blocks.

# Python-Markdown
import markdown
html = markdown.markdown(text, extensions=['tables', 'fenced_code'])

# mistune
import mistune
html = mistune.html(text)

# commonmark
import commonmark
html = commonmark.commonmark(text)

Ruby

Ruby developers typically use kramdown (the default in Jekyll) or redcarpet. Both turn a string of Markdown into HTML in one or two lines.

# kramdown
require 'kramdown'
html = Kramdown::Document.new(text).to_html

# redcarpet
require 'redcarpet'
markdown = Redcarpet::Markdown.new(Redcarpet::Render::HTML)
html = markdown.render(text)

Method 5: Static Site Generators

If you are converting Markdown to build a whole website, a static site generator does it for you. You write .md files; the generator converts each one to an HTML page and applies your layout and CSS.

• Jekyll — Ruby-based, powers GitHub Pages.
• Hugo — Go-based and very fast for large sites.
• Gatsby — React-based, reads Markdown through GraphQL.
• Astro — content-focused, with built-in Markdown and MDX support.

You rarely need to call a converter yourself with these tools — the build step handles it.

Markdown to HTML Mapping Table

A quick reference for the HTML tag each common Markdown element produces.

Common Issues

HTML entities in Markdown

Most converters pass raw HTML in your Markdown straight through, and automatically escape special characters like &, <, and > in plain text. Inside code spans and fenced code blocks, these are always escaped so they display literally. If a tag you meant to show as text disappears, put it in backticks.

Use `<div>` to wrap content.
AT&T and 5 < 6 are escaped automatically.

Losing custom CSS

Converters output bare HTML. The styling you saw in an editor preview, GitHub, or MDViewer comes from a stylesheet, not from the HTML itself. After conversion, link a stylesheet or wrap the output in a template. With Pandoc, use -s -c style.css.

GFM features not converting

Tables, task lists, strikethrough, and autolinks are GitHub Flavored Markdown extensions. A converter running in strict CommonMark mode will leave them as plain text. Enable the GFM option or extension in your tool — for example pandoc -f gfm, or the tables extension in Python-Markdown. GitHub-specific alerts such as > [!NOTE] are not part of standard Markdown at all, and usually need a plugin or post-processing step. See the GitHub Flavored Markdown guide for what is included.

Image paths breaking

Markdown stores image paths exactly as you typed them. If you convert docs/page.md to HTML and move the result to another folder, a relative path like ![logo](images/logo.png) may no longer point to the right file. Keep the HTML and images in the same relative layout, or use absolute URLs.

Untrusted input

If you convert Markdown written by other people (comments, user uploads), the output can contain raw HTML including scripts. Sanitize the HTML with a library such as DOMPurify before showing it on a page.

FAQ

How do I convert a Markdown file to HTML?

The fastest way is Pandoc: install it and run pandoc input.md -o output.html. For a one-off, paste your Markdown into an online tool and copy the HTML. In VS Code, use the Markdown All in One extension's Print current document to HTML command. In code, call a library such as marked.parse() or markdown.markdown().

What is the best tool to convert Markdown to HTML?

It depends on the job. For a quick one-off, use an online converter. For batch conversion and full documents, Pandoc is the most flexible. For web apps and build scripts, marked or markdown-it are the usual choices. For whole websites, a static site generator such as Jekyll, Hugo, or Astro handles conversion automatically.

Can I convert Markdown to HTML with CSS styling?

Yes. Converters produce plain HTML, so you add the CSS yourself. With Pandoc, pandoc input.md -s -c style.css -o output.html creates a standalone page linked to your stylesheet. With a library, wrap the generated HTML in a template that includes your stylesheet. A ready-made stylesheet like github-markdown-css gives you a GitHub-style look with one extra class on the wrapper element.

Preview Your Markdown with MDViewer

Before you convert, check how your Markdown renders. MDViewer is a native macOS app for reading and previewing Markdown files — double-click any .md file in Finder and see it rendered instantly. No Mac handy? Paste your Markdown into the Online Viewer at getmd.ma/viewer/ and see the rendered result in your browser. Lite is free; Pro adds editing, Git history, and PDF export.

Requires macOS 13.0 or later. Intel and Apple Silicon.