How to convert readme.md to clean semantic html
- Step 1Paste the README or drop README.md — Paste the Markdown into the input area or drop the
.mdfile. The tool accepts a single file (acceptsMultipleis false); to combine several docs first, run md-merger, then convert the merged file here. - Step 2Decide: full document or fragment — Leave Full document ON to get a complete, openable
.htmlpage with a built-in stylesheet — good for GitHub Pages or sending a single file to someone. Turn it OFF to get just the body HTML (no<html>/<head>/<style>) for pasting into an existing site template or a CMS rich-text field. - Step 3Run the conversion —
markedparses the README locally and renders HTML in milliseconds. Nothing is uploaded; the conversion happens in your browser tab. - Step 4Check code blocks and badges in the preview — Confirm fenced blocks kept their
language-*class and that badge/shield<img>HTML rendered. If you rely on syntax highlighting, remember the class hook is present but no colouring library is included — add highlight.js to the page yourself. - Step 5Add heading ids if you need in-page anchors — marked does NOT add
idattributes to headings, so README TOCs that link to#installationwill not scroll. If you need working anchors, addidattributes to the headings in the output, or keep the TOC as a GitHub-only convenience and drop it from the standalone HTML. - Step 6Copy or download README.html — Copy the HTML source or download the
.htmlfile (named after your input). For a GitHub-styled look instead of the plain built-in stylesheet, use the sibling md-to-github-html tool, which loads GitHub's Primer CSS.
What converts (marked v14 defaults)
Verified against marked 14.1.4 as shipped in this tool. GFM extensions are enabled by default; several common Markdown extensions are NOT part of core marked.
| README element | Input | HTML output | Supported? |
|---|---|---|---|
| Headings | ## Install | <h2>Install</h2> (no id) | Yes — but no anchor id |
| GFM table | | a | b | rows | <table><thead>…</thead><tbody>…</tbody></table> | Yes |
| Fenced code | ` python ` | <pre><code class="language-python"> | Yes — class only, no colouring |
| Task list | - [x] done | <li><input checked disabled type="checkbox"> | Yes |
| Strikethrough | ~~old~~ | <del>old</del> | Yes |
| Bare URL | https://x.com | <a href="https://x.com">https://x.com</a> | Yes (GFM autolink) |
| Badge / inline HTML | <img src="…shields.io…"> | passed through verbatim | Yes — not sanitized |
| Footnote | text[^1] | broken link <a href="1">^1</a> | No — not in core marked |
Full document vs fragment
The single option (fullDocument, default true) decides whether you get a complete page or just the body.
| Setting | Output wrapper | Stylesheet | Use it for |
|---|---|---|---|
| Full document (default) | <!DOCTYPE html> + <head> + <body> | Built-in minimal system-font CSS (max-width 860px, styled pre/code/table/blockquote) | A standalone openable page, GitHub Pages index, or single-file handoff |
| Fragment (option OFF) | Body HTML only — no <html>/<head>/<style> | None — inherits your page's CSS | Pasting into an existing site template, docs theme, or CMS rich-text field |
Tier limits (markdown family)
Limits are per file. The character limit is separate from the byte size — a multibyte README can hit the char limit before the MB limit.
| Plan | Max file size | Max characters | Files per run |
|---|---|---|---|
| Free | 1 MB | 500,000 | 1 |
| Pro | 10 MB | 5,000,000 | 10 |
| Pro + Media | 50 MB | 20,000,000 | 50 |
| Developer | 500 MB | unlimited | unlimited |
Cookbook
Real README snippets and the exact HTML this tool produces — including the cases that trip up maintainers.
README badge row survives conversion
Most READMEs open with a row of Shields.io badges written as raw HTML or Markdown image links. marked passes inline HTML through verbatim, so the badges remain functional in the output.
Input (README.md): # my-lib   Output (fragment): <h1>my-lib</h1> <p><img src="https://img.shields.io/badge/build-passing-green" alt="build"> <img src="https://img.shields.io/npm/v/my-lib" alt="npm"></p>
Install table and fenced code block
GFM tables and language-tagged code fences are the README workhorses. The table becomes a full <table>; the code block keeps its language class for later highlighting.
Input: | Step | Command | |------|---------------| | 1 | npm install | ```bash npm run build ``` Output (body): <table> <thead><tr><th>Step</th><th>Command</th></tr></thead> <tbody><tr><td>1</td><td>npm install</td></tr></tbody> </table> <pre><code class="language-bash">npm run build </code></pre>
Task-list roadmap renders as checkboxes
A '## Roadmap' section written with GFM task lists converts to disabled HTML checkboxes — visually identical to how GitHub shows them.
Input: ## Roadmap - [x] CLI - [ ] Web UI Output: <h2>Roadmap</h2> <ul> <li><input checked disabled type="checkbox"> CLI</li> <li><input disabled type="checkbox"> Web UI</li> </ul>
README TOC links do NOT resolve in the HTML
Maintainers paste a GitHub-generated TOC of #anchor links into the README. Because marked emits headings without id attributes, those anchors point at nothing in the standalone HTML. Generate the TOC with the sibling tool if you want one, but expect to add ids for working anchors.
Input: ## Table of Contents - [Install](#install) ## Install ... Output: <h2>Table of Contents</h2> <ul><li><a href="#install">Install</a></li></ul> <h2>Install</h2> <!-- no id="install", so the link dead-ends --> Fix: add id="install" to the <h2> in the output by hand.
Fragment mode for embedding in a docs site
When the HTML goes inside an existing theme, you do not want a second <html>/<head>. Turn Full document OFF to get just the body, then paste it into your template's content slot.
Full document OFF → output is body only: <h1>my-lib</h1> <p>A tiny library.</p> (No <!DOCTYPE>, <head>, or <style> — your site's CSS styles it.) Full document ON → same content wrapped in a complete page with the built-in stylesheet and <title>Document</title>.
Edge cases and what actually happens
Headings have no id attributes
By designmarked v14 (as configured here) does not generate id slugs on headings. A README TOC of [Install](#install) links renders as anchors but they point at headings with no matching id, so clicking does nothing in the standalone HTML. This is the most common README surprise. Add ids manually in the output, or treat the TOC as GitHub-only and remove it from the exported page.
Raw HTML and <script> pass through unsanitized
Not sanitizedmarked does not strip HTML. Badge <img> tags, alignment <div align="center"> wrappers, and even <script> survive verbatim in the output. For trusted README content this is what you want (badges keep working). If you are converting an untrusted README and will host the result, sanitize the output HTML before serving it.
Footnotes render as broken links
Not supportedFootnote syntax (text[^1] with [^1]: note at the bottom) is NOT part of core marked. text[^1] is parsed as a reference-style link and emits a broken <a href="1">^1</a>. If your README uses footnotes, convert them to inline links or a manual references section before converting — see md-footnote-linker for the inverse of this.
No syntax highlighting in code blocks
By designFenced code blocks get class="language-bash" but no per-token colour spans — marked emits the class hook only. The output looks like grey monospace until you add highlight.js or Prism to the page (full-document output includes a simple pre/code background but no colouring).
Relative image paths are preserved verbatim
Preserved becomes <img src="./docs/arch.png"> with the relative path unchanged. The standalone HTML will only show those images if it sits in the same directory structure. To rewrite paths to absolute CDN URLs before converting, run md-image-path-rewriter first.
Not the same as GitHub's rendered look
ExpectedFull-document output uses a minimal built-in stylesheet, not GitHub's Primer CSS, so the page will not look pixel-identical to github.com. For a GitHub-accurate render, use md-to-github-html, which loads Primer CSS from CDN.
Math expressions stay literal
Not supportedmarked does not parse LaTeX/MathJax. $E = mc^2$ and $$…$$ blocks pass through as literal text. If your README documents formulas, normalise the delimiters with md-math-normalizer and add a KaTeX/MathJax script to the rendered page yourself.
Emoji shortcodes are not expanded
Not supportedGitHub-style shortcodes like :rocket: are left as literal text — marked has no emoji shortcode map. Unicode emoji you typed directly (🚀) survive fine. To strip or normalise emoji before converting, use md-emoji-remover.
File exceeds the free-tier character limit
400 rejectedA README over 500,000 characters (or 1 MB) is rejected on the Free plan with a character-count error before conversion. Most READMEs are well under this; monorepo mega-READMEs may not be. Pro raises the cap to 5,000,000 characters / 10 MB.
MDX-specific syntax is not interpreted
Treated as text/HTMLIf your README is actually an .mdx file with JSX components, marked does not execute them. JSX tags are treated as raw HTML (passed through, not rendered as components). Convert MDX with a real MDX toolchain; this tool targets CommonMark + GFM.
Frequently asked questions
Is the output a full HTML document or just a fragment?
Your choice. The Full document option is ON by default and wraps the output in a complete <!DOCTYPE html> page with <head>, a built-in system-font stylesheet, and <title>Document</title>. Turn it OFF to get only the body HTML (no <html>/<head>/<style>) for pasting into an existing template or CMS.
Does it support GitHub Flavored Markdown features?
Yes — GFM is on by default in the marked engine. Pipe tables, ~~strikethrough~~, - [ ] task lists, and bare-URL autolinks all convert to their HTML equivalents. What is NOT supported (because it is not in core marked): footnotes, :emoji: shortcodes, and LaTeX math.
Why don't my README's table-of-contents links work in the HTML?
marked emits headings without id attributes, so [Install](#install) has nothing to scroll to in the standalone page. This is the single most common surprise. Either add id attributes to the headings in the output by hand, or accept that the TOC is a GitHub-only convenience and remove it from the exported HTML.
Will my Shields.io / build-status badges still work?
Yes. Badges are inline HTML or Markdown image links, and marked passes inline HTML through verbatim and converts  to <img>. The badge URLs are unchanged, so they render the same in the output as on GitHub — as long as the page can reach the badge host.
Does it add syntax highlighting to code blocks?
No — it adds the class hook (class="language-bash") but no colour markup. The output is dependency-free grey monospace until you load highlight.js or Prism on the rendered page. This keeps the standalone HTML small and self-contained.
How do I make it look like GitHub renders my README?
Use the sibling tool md-to-github-html, which loads GitHub's Primer CSS so the page matches github.com closely. This tool's full-document mode uses a simpler built-in stylesheet instead.
Is raw HTML in my README sanitized?
No. marked passes HTML through verbatim — including <div align>, <details>, and even <script>. For a trusted README this is desirable (your badges and collapsible sections keep working). If you are converting an untrusted README and will host the result, sanitize the HTML before serving.
What happens to relative image and link paths?
They are preserved exactly — ./docs/img.png stays ./docs/img.png. The standalone HTML only shows those images if it lives in the same folder structure. To convert local paths to absolute CDN URLs before conversion, run md-image-path-rewriter first.
Can I convert a private or unreleased README safely?
Yes. The conversion runs entirely in your browser via marked — the README is never uploaded. Only an anonymous 'file processed' counter is recorded for signed-in dashboard stats, never the content.
Can it convert several README files at once?
No — this tool takes one file per run. To combine multiple docs into one page, merge them first with md-merger (Pro for more than two files), then convert the merged file here.
How big a README can I convert?
Free: up to 1 MB or 500,000 characters per file. Pro: 10 MB / 5,000,000 characters. Pro + Media: 50 MB / 20,000,000. Developer: 500 MB / unlimited. The character cap is separate from the byte size, so a heavily multibyte README can hit the char limit first.
What file name does the download get?
The output is named after your input with the extension swapped to .html — README.md becomes README.html. .mdx, .markdown, and .txt inputs are handled the same way.
Privacy first
All Markdown processing runs locally in your browser using JavaScript. No file is ever uploaded to JAD Apps servers — only metadata counters are saved for signed-in dashboard stats.