DEV Community

Mubeen Khan
Mubeen Khan

Posted on

Markdown Is Not HTML, But It Was Born to Become It

#beginners #javascript #tutorial #webdev

Markdown Is Not HTML, But It Was Born to Become It

Every README, every GitHub issue, every docs page you have ever written in Markdown ends up as HTML. That is not an accident. Markdown was designed in 2004 by John Gruber as a writing syntax that converts cleanly to HTML, nothing more. If you have ever wondered what actually happens between the # you type and the <h1> the browser renders, this post walks through it, with a converter you can try as you read.

The mapping is simpler than you think

Markdown has a small set of constructs, and each one maps to exactly one HTML element:

  • # Title becomes <h1>Title</h1>
  • **bold** becomes <strong>bold</strong>
  • - item becomes <li>item</li> inside a <ul>
  • `code` becomes <code>code</code>
  • [text](https://example.com) becomes <a href="https://example.com">text</a>

That is the whole trick. A converter reads the Markdown, works out the structure line by line, and writes the matching tags. There is no magic and no server needed. The conversion is pure text processing, which is why it runs instantly in a browser tab.

Where GitHub Flavored Markdown adds value

Plain Markdown covers the basics. GitHub Flavored Markdown, the dialect GitHub, Dev.to, and most docs tools actually use, adds three things developers reach for constantly: tables, task lists, and autolinks.

A table written with pipes:

| Syntax | Becomes |
| --- | --- |
| `# Title` | `<h1>Title</h1>` |
Enter fullscreen mode Exit fullscreen mode

becomes a real <table> with <thead> and <tbody>, not a picture of a table. A checklist written as - [x] Done becomes a list item with a checked checkbox. A bare URL becomes a clickable link without any extra syntax. If your converter does not handle these three, it is converting 2004 Markdown, not the Markdown people write today.

The one safety rule most converters skip

Here is the part worth paying attention to. A converter that passes raw HTML straight through will also pass a <script> tag straight through. Paste a document containing one into a converter like that, copy the output into your CMS, and you have just shipped executable code to your readers.

A safe converter escapes source HTML before parsing, so only tags the parser itself generates can appear in the output. The <script> becomes harmless text. This matters every time you paste Markdown written by someone else, a README from a pull request, a doc from a contractor, into your own site.

Try it on a real document

If you want to see the mapping on your own text, this free Markdown to HTML converter runs entirely in your browser: paste Markdown on the left, and it shows a live rendered preview next to the raw HTML source, with GFM tables, task lists, and fenced code blocks supported. You can copy the HTML or download it as a complete standalone .html file, and because the output is sanitized, it is safe to paste straight into WordPress, Ghost, or any CMS that accepts raw HTML.

Next time you write a README, remember what it becomes. Markdown is the draft. HTML is the destination. A good converter just makes the trip visible.

Top comments (0)