Why Copy-Pasting a Web Page Into a README Never Looks Right

You've found the right paragraph on a web page, or exported a document out of a CMS, and now you need it in a README, a wiki page, or a Markdown-based note. Paste it directly and one of two things happens: either you get a wall of raw HTML tags sitting in your Markdown file, or your editor's rich-paste feature tries to guess at formatting and gets some of it wrong. Neither gives you clean, working Markdown.

What actually goes wrong with a direct paste

A plain-text paste strips all the formatting - bold, links, headings, lists all collapse into a flat paragraph, and you lose information you actually wanted to keep. A rich paste, where your editor tries to be smart about it, sometimes preserves formatting correctly and sometimes doesn't, depending on exactly how the source page structured its markup - and you usually only find out which happened after scrolling through the result looking for problems.

Who runs into this regularly

A developer writing documentation who found the exact explanation they need on someone else's page and wants it in their own README, correctly formatted, without retyping it by hand. A writer moving content out of a CMS export into a Markdown-based blog or wiki, where the CMS's own export is HTML and the destination speaks Markdown. Anyone pasting an AI response's formatted output into a note-taking app that expects Markdown syntax rather than raw HTML tags.

Why hand-cleaning HTML tags is slower than it looks

Stripping tags by hand seems simple for one paragraph, but real pasted content usually has a mix of headings, a list or two, a link, some bold and italic text, maybe a code snippet - and hand-converting each of those to its correct Markdown syntax, correctly, without introducing a typo in a link URL, adds up fast for anything longer than a sentence.

What a proper conversion actually does

Converting HTML to Markdown properly means walking the actual structure of the page - which elements are headings, which text is inside a link, which list is ordered versus not - rather than guessing from how the pasted text visually looks. That's the difference between a converter and a strip-tags script: a converter understands the markup, a strip-tags script just deletes it and hopes the result still makes sense.

Where this fits

HTML to Markdown converts pasted HTML into clean Markdown live, as you paste, entirely inside your browser. The how-to guide covers the actual steps.