Why We're Restructuring This Blog: From HTML Templates to Content Blocks
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.
What We Lost
When HTML became presentational, we lost the ability to separate content from presentation. Our articles weren't just "text with some key takeaway boxes"—they were "div elements with Bootstrap card classes containing unordered lists with specific CSS styling."
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:
Example: This Very Card
This highlighted box is defined as:
"type": "card"- semantically, it's a highlighted content block"header": "Example: This Very Card"- the title of the block"content": "This highlighted box..."- the main text content"list": [...]- bullet points within the block
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:
JSON Block Structure
Each block has a type (paragraph, heading, card, list) and data specific to that type. A paragraph block contains text content, while a card block contains header, content, and optional list items.
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.
The Bottom Line
We've essentially created what HTML should have remained: a semantic content format that preserves meaning while enabling rich presentation through a clean separation layer.
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.