Markdown to HTML

What Actually Happens When You Convert Markdown to HTML

Markdown was never designed to be a final format. John Gruber created it in 2004 as a writing tool — a way to compose readable plain text that could be converted to valid HTML without you touching angle brackets. The conversion step is where the real work happens, and understanding what goes on under the hood changes how you write Markdown in the first place.

When a Markdown-to-HTML tool processes your input, it runs a parser that walks through your text token by token. A hash symbol at the start of a line becomes an <h1>. Two hashes become <h2>. An asterisk-wrapped word becomes <em>. But the interesting cases are the edge ones — what happens to a blank line inside a list? What does the tool do with an image reference that has no alt text? These decisions reveal the quality of the parser underneath.

The Image Syntax Problem Most People Get Wrong

Since this is categorized as an image and photo tool, let's start there. Markdown's image syntax looks almost identical to its link syntax, with one added exclamation mark:

![A golden retriever sitting in afternoon sun](dog-portrait.jpg)

That bang prefix tells the parser to render an <img> tag instead of an anchor. The text inside brackets becomes the alt attribute — and this is where most people's output falls apart. Many users write:

![](dog-portrait.jpg)

That empty alt attribute is technically valid HTML, but it's an accessibility failure. Screen readers will either skip the image or announce the filename. A good Markdown-to-HTML converter won't fix this for you, because it can't — it doesn't know what's in your image. What it will do is faithfully reproduce the empty alt, which means the responsibility is entirely yours at the writing stage.

The title attribute (the optional third element) is even more commonly forgotten. The syntax puts it in quotes after the path:

![A golden retriever sitting in afternoon sun](dog-portrait.jpg "Photo taken at Lodhi Garden, 2024")

This becomes a tooltip on hover in most browsers. For photo galleries or portfolios, that title attribute is free metadata that most Markdown authors never use because they don't realize the converter will pick it up.

Reference-Style Images and Why They Matter for Photo-Heavy Documents

If you're working on a document with dozens of images — a photo essay, a product catalog, technical documentation with screenshots — inline image syntax becomes a maintenance nightmare. Change one directory path and you're doing find-and-replace across the whole file.

Reference-style syntax solves this. You define images like variables:

![Mountain sunrise][sunrise-ref]

[sunrise-ref]: /photos/himachal/sunrise-2024.jpg "Sunrise from Triund, October 2024"

All your image definitions can live at the bottom of the document. When the Markdown-to-HTML tool processes this, it resolves the reference and produces exactly the same <img> output as inline syntax. But now if you move your images to a CDN, you update one line per image, not one line per usage.

How the Converter Handles Relative Versus Absolute Paths

This is a practical concern that trips up almost everyone using Markdown-to-HTML for actual web content. The converter doesn't modify your paths — it copies them verbatim into the src attribute. So if you write:

![Screenshot](screenshots/dashboard.png)

The output HTML will have src="screenshots/dashboard.png". Whether that resolves correctly depends entirely on where the HTML ends up being served from. If your HTML is at https://example.com/docs/guide.html, the browser will look for the image at https://example.com/docs/screenshots/dashboard.png.

This is not a limitation of the tool — it's how HTML path resolution works. But it means that before converting, you need to know where the output will live. Absolute paths (/images/photo.jpg or https://cdn.example.com/photo.jpg) are always safer for converted documents.

What the HTML Output Actually Looks Like

Let's trace a realistic Markdown snippet through conversion. Input:

## My Photography Setup

I shoot with a **Fujifilm X-T5** paired with the 35mm f/1.4 lens.

![Fujifilm X-T5 camera body](camera.jpg "My primary camera since 2023")

Key reasons I chose this system:

- Compact body despite large sensor
- Film simulations built into RAW files
- [Good community resources](https://fujifilm-community.example.com)

A standards-compliant Markdown-to-HTML converter produces:

<h2>My Photography Setup</h2>
<p>I shoot with a <strong>Fujifilm X-T5</strong> paired with the 35mm f/1.4 lens.</p>
<p><img src="camera.jpg" alt="Fujifilm X-T5 camera body" title="My primary camera since 2023"></p>
<p>Key reasons I chose this system:</p>
<ul>
<li>Compact body despite large sensor</li>
<li>Film simulations built into RAW files</li>
<li><a href="https://fujifilm-community.example.com">Good community resources</a></li>
</ul>

Notice that the image is wrapped in a <p> tag. This is standard CommonMark behavior — a standalone image on its own paragraph gets paragraph wrapping. If you're integrating this output into a CSS grid layout for a gallery, you may need to target p > img in your styles rather than just img.

Extended Markdown Features That Affect Image Rendering

Basic Markdown (the original Gruber spec) doesn't support image sizing or alignment — there's no native syntax for width or float. Different tools handle this differently. Some support extended attribute syntax:

![Portrait photo](portrait.jpg){width=400 height=600}

Others let you drop raw HTML inline, since Markdown parsers generally pass HTML through unchanged:

<img src="portrait.jpg" alt="Portrait photo" width="400" style="float:right; margin:0 0 1em 1em">

If your use case involves layout control — wrapping text around images, specifying dimensions to prevent layout shift (important for Core Web Vitals), or lazy loading — you'll need to either use a converter that supports extended attributes, or write those specific images as raw HTML within your Markdown document.

Using the Converted Output in Real Projects

1. Blog posts and CMS content: Convert your Markdown and paste the HTML body into your CMS's HTML editor. The heading hierarchy, inline formatting, and image tags carry over cleanly. Watch for CMS-injected image wrappers that might double-wrap your content.
2. Email templates: Email clients are notoriously hostile to CSS. The bare semantic HTML from a Markdown converter — particularly the inline <strong> and <em> tags — tends to survive email rendering better than complex div structures. Add inline styles after conversion.
3. Documentation sites: Tools like Jekyll, Hugo, and Docusaurus take your Markdown directly and run their own converters, so you'd use the raw .md files. But if you're building custom documentation without a static site generator, converting to HTML first and then templating it in is a valid workflow.
4. Portfolio pages: For photographers building a simple gallery page, writing image references in Markdown and converting to HTML is faster than writing HTML by hand. Combine with a CSS grid template and you have a functional gallery with minimal effort.

The Part Nobody Talks About: Character Encoding in Filenames

If you're working with image filenames that contain spaces or non-ASCII characters — common with photos from phones or cameras on non-English systems — Markdown-to-HTML converters will put those filenames directly into the src attribute. A file named Holi Festival 2024.jpg becomes src="Holi Festival 2024.jpg", which breaks in most browsers.

Browsers expect URLs to be percent-encoded: src="Holi%20Festival%202024.jpg". Some converters do this encoding automatically. Others don't. The reliable fix is to rename your files before writing the Markdown — replace spaces with hyphens and stick to ASCII characters. This is good practice regardless of which tool you're using.

Reading the Output Before You Ship It

The most useful habit when working with any Markdown-to-HTML converter is actually reading the output. Not the preview — the raw HTML. Paste it into a validator at validator.w3.org to catch unclosed tags, missing alt attributes, or malformed nesting. A five-second validation step catches the kind of errors that are embarrassing to find after a document is live.

Markdown-to-HTML conversion is a narrow, well-solved problem. The value of a good tool is in handling the edge cases correctly — nested lists, code blocks inside blockquotes, image titles with quotes in them — without requiring you to think about the parser. Write clean Markdown with meaningful alt text, use reference-style syntax for image-heavy documents, and validate the output. That's the whole discipline.