Converting Markdown Documentation to HTML for Static Sites

Last month I rewrote our internal API docs. Everything was in markdown because that's what developers actually write. But we needed HTML pages that non-technical people could browse. No fancy framework, just clean static files.

Here's what I learned about getting markdown into HTML for documentation sites.

Why markdown files need conversion for static sites

Markdown is perfect for writing. You can version control it, review it in pull requests, and edit it in any text editor. But browsers don't render markdown files. They download them.

Static site generators like Jekyll or Hugo handle this conversion automatically. But sometimes you don't need a whole build system. Maybe you have 10 markdown files and just want HTML. Maybe you're testing locally before committing to a framework. Maybe your deployment process is already set up for plain HTML.

I've done it both ways. The browser-only approach works well up to about 50 pages. After that, you want automation.

Quick conversion for small documentation sets

For under 20 files, I just convert them individually. Open each markdown file in a browser tool like Markdown to HTML, copy the output, save as .html.

The tedious part is styling. You'll want consistent CSS across all pages. I create one template.html with the navigation and CSS, then paste converted content into the body. Takes maybe an hour for a dozen pages.

Real benefit here: no dependencies, no build step, no Node modules eating disk space. You get clean HTML files you can edit directly if needed.

What breaks in documentation when converting markdown

Code blocks lose syntax highlighting unless your converter adds it. Most browser tools output plain <pre><code> blocks. You need to either:

• Add a JavaScript highlighter like Prism.js to your template
• Use a converter that bakes in highlighted HTML
• Accept plain code blocks (honestly fine for most docs)

Internal links need fixing. If you wrote [See API reference](api.md), that becomes a broken link in HTML. Change all .md references to .html before converting, or do a find-replace after.

Image paths usually work fine if they're relative. But absolute paths like /images/diagram.png might break depending on where you're hosting.

Tables convert cleanly. Lists too. The main gotchas are code and links.

Adding navigation and structure to converted pages

Static documentation needs a navigation menu. You're building this yourself since you're not using a generator.

I make a nav.html snippet: