Why We're Restructuring This Blog: From HTML Templates to Content Blocks

2025-05-24 by Dan Quellhorst

If you're reading this article, you're seeing the result of a significant architectural change to how this blog works. What looks the same on the surface represents a fundamental shift from hardcoded HTML templates to a flexible block-based content system.

The Problem We Had

Like many developers, I built this blog the "quick" way: individual HTML templates for each article, with content mixed directly into presentation markup. It worked fine for a handful of posts, but as the site grew to 60+ articles, the problems became clear:

• Repetitive code: The same card structures, headers, and layouts copied across dozens of files
• Design lock-in: Changing the appearance of content blocks required editing every single article
• Content trapped in markup: Article content was inseparable from Bootstrap classes and HTML structure
• Maintenance burden: Simple styling changes became multi-file editing sessions

The HTML Identity Crisis

HTML was originally designed to be semantic—to describe the meaning of content, not its appearance. A heading was <h1> because it was semantically a heading, not because of how it looked.

But somewhere along the way, HTML became a presentation language. Instead of semantic markup, we ended up with <div class="card mb-4 shadow-lg border-0"> where the CSS classes do all the real work of describing what something is.

Why Not Markdown?

Markdown solved the "too much HTML complexity" problem beautifully. It gave us clean, readable content that could be written by humans and understood by machines. But Markdown has limitations for rich content:

• No standard way to represent complex structures like comparison tables
• Limited semantic block types beyond basic formatting
• Extension syntax varies wildly between platforms
• Difficult to add styling hints or layout information

Markdown was perfect for simple documents, but modern web content needs more structure.

Enter Content Blocks

Instead of fighting with HTML or extending Markdown, we decided to treat content as structured data. Each article is now composed of semantic blocks that describe what the content is, not how it should look:

The actual styling—Bootstrap classes, colors, spacing—gets applied when the block is rendered, not stored with the content.

The Benefits Are Immediate

Even with just one article converted to this system, the advantages are clear:

• Design consistency: All card blocks use the same template, so they always look identical
• Easy updates: Changing how cards look requires editing one template file, not dozens of articles
• Content portability: The same content could render as HTML, mobile app screens, or even voice assistant responses
• Reusable components: Complex structures like comparison tables become reusable block types

Technical Implementation

The technical approach is straightforward. Articles are stored as JSON files with a simple structure:

When someone requests an article, the system loads the JSON, loops through the blocks, and renders each one using its corresponding template. The routing system tries JSON articles first, then falls back to the old HTML templates for backward compatibility.

Why This Matters

This isn't just a technical exercise. It's about creating content that outlasts any particular technology choice. Whether this site runs on Flask, Django, React, or something that hasn't been invented yet, the content remains portable and reusable.

More importantly, it restores the separation between content and presentation that we lost when HTML became a styling language. Content describes meaning; templates handle appearance.

It's funny how technology evolves. We started with semantic HTML, moved to presentational HTML mixed with CSS frameworks, and now we're back to structured content—but this time we're keeping the layers properly separated.