Markdown on Ikwuka Okoye

From Markdown to HTML: Designing the Static Site Generator Pipeline

Tue, 11 Aug 2026 00:00:00 +0000

From Markdown to HTML: Designing the Static Site Generator Pipeline

A static site generator is fundamentally a transformation system.

It takes source content, processes that content through a series of stages, and produces files that can be served directly to users.

For my static site generator, the core transformation looks like this:

Markdown
 ↓
Blocks
 ↓
Block Types
 ↓
Inline Text Nodes
 ↓
HTML Nodes
 ↓
HTML

The value of this architecture is not simply that it works.

Building a Static Site Generator in Python: From Markdown to HTML

Mon, 10 Aug 2026 00:00:00 +0000

Building a Static Site Generator in Python: From Markdown to HTML

A static site generator looks simple from the outside.

You write some Markdown, run a command, and HTML files appear in an output directory.

The interesting engineering work happens between those two points.

Building a static site generator from scratch is a useful exercise because it exposes several concepts that are normally hidden behind frameworks and libraries: parsing, intermediate representations, tree structures, rendering, filesystem operations, and deterministic builds.

Converting Markdown Blocks into Semantic HTML

Mon, 10 Aug 2026 00:00:00 +0000

Converting Markdown Blocks into Semantic HTML

Markdown documents are written as a continuous stream of text, but browsers consume structured HTML.

Bridging those two representations requires more than replacing a few characters.

A static site generator needs to understand the boundaries between blocks and determine what each block represents.

That was one of the central problems in my Static Site Generator project.

What Is a Markdown Block?

A block is a logical unit of Markdown content.

Parsing Markdown into an HTML Tree: Designing the Intermediate Representation

Mon, 10 Aug 2026 00:00:00 +0000

Parsing Markdown into an HTML Tree: Designing the Intermediate Representation

One of the easiest mistakes to make when building a Markdown-to-HTML converter is to think of the problem as string replacement.

Replace **text** with <strong>text</strong>.

Replace *text* with <em>text</em>.

Replace headings with <h1>.

At first, this seems sufficient.

It quickly becomes difficult once documents contain nested structures.

A more robust approach is to introduce an intermediate representation between Markdown and HTML.

Testing a Static Site Generator: Small Contracts, Reliable Output

Mon, 10 Aug 2026 00:00:00 +0000

Testing a Static Site Generator: Small Contracts, Reliable Output

A static site generator is a good example of a system where small bugs can propagate through multiple layers.

A mistake in Markdown parsing can eventually appear as malformed HTML.

A malformed text node can produce incorrect links.

A block-classification error can cause an entire section of a page to render incorrectly.

That makes testing especially important.

The solution is not necessarily hundreds of large end-to-end tests.