How the conversion works
The tool parses your HTML into a tree the way a browser would, forgiving unclosed tags, unquoted attributes and stray end tags. Then it walks the tree and writes GitHub Flavored Markdown, which builds on the CommonMark spec. Whitespace is collapsed the way a browser renders it, so the indentation in your source doesn’t leak into the output. Only <pre> blocks keep their spacing.
- Code. Inline code gets a backtick fence longer than any run of backticks inside it. Blocks become fenced code, and a
language-jsorlang-jsclass becomes the fence language. - Links and images. Titles are kept. Add the page’s URL in “Resolve relative links against” and
/docsbecomes a full URL, which matters when the Markdown moves to a different site. - Tables. The header comes from <thead> or the first row. Pipes in cells are escaped, colspan and rowspan get empty filler cells, and single-column layout tables (common in emails) are unwrapped into normal paragraphs.
- Escaping. Text that would accidentally become Markdown, like a paragraph starting with “1.” or “#”, gets a backslash. Underscores inside words (snake_case) are left alone because they can’t trigger emphasis.
Where it can’t match the HTML
Markdown has no underline, colors, merged cells or nested tables, so those are simplified. Bold text that ends in punctuation right before a letter (<b>Note:</b>text) can’t be written with asterisks, so it stays as a <strong> tag, which GitHub renders fine. Definition lists become a bold term followed by its definition, and <details> becomes a bold summary line.
Copying from a document instead?
If you’re moving text out of Google Docs or Word, use Paste to Markdown: it reads the clipboard directly and strips the extra markup those apps add. For data, try the CSV, JSON or XML converters. Once the post is in Markdown, check its length with the word counter and the reading time calculator.