Working with Markdown to HTML workflows

Many teams write content in Markdown and convert it to HTML for the web. README files, blog drafts, documentation, and CMS exports often arrive as .md files. Worth knowing when that workflow helps, what the conversion usually gets wrong, and how to keep the HTML clean on the other side.

You already know HTML structure. Markdown is a shorthand for the common bits – headings, paragraphs, links, lists – not a replacement for thinking about semantics.

What Markdown gives you

Markdown lets you write this:

## Installation

Download the release, then run:

    npm install

See the [docs](/docs/) for configuration.

A converter turns it into HTML roughly like:

<h2>Installation</h2>
<p>Download the release, then run:</p>
<pre><code>npm install</code></pre>
<p>See the <a href="/docs/">docs</a> for configuration.</p>

Faster to type than hand-wrapping every paragraph. Fine for articles, docs, and changelogs. Less fine when you need precise landmark regions, complex tables, or custom data attributes on every element.

Common conversion tools

Pick a tool and know its defaults:

Pandoc – command-line swiss army knife; supports many input and output formats.
marked, markdown-it, Showdown – JavaScript libraries, often used in static site generators and build scripts.
Static site generators – Eleventy, Hugo, Jekyll, Astro: Markdown in, HTML pages out, usually with a layout template wrapped around the converted body.
GitHub / GitLab – render Markdown in the browser for README and wiki content (their HTML output is not always what you want to paste blindly into your site).

Example with Pandoc from a terminal:

pandoc article.md -o article.html --standalone

--standalone adds <html>, <head>, and <body> around the converted fragment. Without it you get only the inner content, which is what you want when dropping Markdown into a layout template.

Front matter and layouts

Many workflows put metadata at the top of a Markdown file:

---
title: Boiler servicing guide
description: What we check during an annual service
date: 2026-07-28
---

## Before we arrive

Clear access to the boiler cupboard...

The build step reads the YAML front matter, sets the page <title> and meta description, wraps the converted HTML in a site layout, and writes boiler-servicing.html. You author in Markdown; the generator handles the repetitive document shell.

Markdown vs hand-written HTML

Use Markdown when:

Content is mostly prose, headings, lists, and code samples.
Non-developers need to edit copy without touching tags.
You have a reliable build step between source and production.

Prefer HTML when:

You need specific landmarks, ARIA, or microdata on particular elements.
Layout is component-heavy (grids of cards, complex forms).
You are fine-tuning accessibility and every tag choice matters.

Hybrid setups are normal: Markdown for the article body, HTML partials for site chrome and embedded components.

Raw HTML inside Markdown

Most Markdown flavours allow inline HTML when you need it:

## Pricing

<table>
  <caption>Standard call-out fees</caption>
  <thead>
    <tr><th scope="col">Service</th><th scope="col">From</th></tr>
  </thead>
  <tbody>
    <tr><td>Emergency</td><td>£120</td></tr>
  </tbody>
</table>

The converter passes through tags it does not understand. Useful for accessible tables; easy to abuse if people paste entire layout divs into Markdown and defeat the point of the workflow.

Sanitise when users supply Markdown

If visitors can post Markdown (comments, forums, wiki edits), treat the converted HTML like any untrusted input. Converters often allow raw HTML in the source. Strip scripts, event handlers, and dangerous URLs on the server before you store or display the result.

Libraries like markdown-it can disable HTML input entirely. That is the safer default for user-generated content.

WordPress note

WordPress stores block editor content as HTML in the database, not Markdown. Plugins can add Markdown authoring, but the published page is still HTML. If you maintain a WordPress site, know whether your theme expects block markup, classic editor HTML, or plain paragraphs – mixing sources without a plan leads to inconsistent components and styling headaches.

Checklist before you ship converted HTML

Heading levels still make a sensible document outline (no skipped levels).
Images from Markdown syntax got meaningful alt text.
Code blocks escaped properly (no accidental script execution in previews).
Links use relative or absolute URLs you trust.
Output validated or spot-checked in the layout it will actually use.

Markdown saves typing. You still own the HTML that reaches the browser.