Quest for Better Blogging: #2 The Architecture of Better Publishing

Understanding why some tools fight you while others amplify your thinking

(source: https://www.cosmicjs.com/blog/static-site-generators-explained-in-5-minutes)

The Rabbit Hole Begins

After documenting the frustrations and systematic failures of my copy-paste workflow, I found myself staring at a deeper puzzle. I understood what was breaking – LaTeX equations becoming image files, code blocks losing syntax highlighting, semantic structure collapsing into visual formatting. But I had no idea why these specific things kept breaking in such predictable ways.

Why did content that rendered perfectly in VS Code’s markdown preview turn into a mangled mess in Medium? What was fundamentally different about how these systems processed identical markdown source? The answer wasn’t just about incompatible formatting – it was about two completely different philosophies of how the web should work.

This question launched me into a fascinating exploration of web architecture, content management evolution, and the hidden complexities lurking behind what seems like simple copy-paste operations. What I discovered would completely reframe how I think about digital publishing and reveal why the solution I was seeking – static site generation – represents both a return to the web’s origins and its most sophisticated evolution.

The Web’s Documentation Journey: A Brief History

To understand why modern publishing tools fight each other so aggressively, we need to step back and examine how online documentation has evolved. The web’s approach to content has come full circle in ways that directly explain my current frustrations.

The Static Era (1990s-early 2000s): The web began with hand-crafted HTML files. Technical documentation was written directly in HTML, often by the same people who created the software being documented. Every page was a static file, carefully structured with semantic markup. Mathematical notation was handled through specialized markup languages, and code examples were formatted with precise HTML structures.

This approach produced some of the most durable technical documentation ever created – pages that still render perfectly decades later. But it required significant technical expertise and made collaboration difficult. You needed to understand HTML, manage file structures manually, and coordinate changes across multiple static files.

The Dynamic Revolution (2000s-2010s): Platforms like WordPress, Drupal, and later Medium solved the collaboration and maintenance problems by moving content into databases and generating pages dynamically. Suddenly, non-technical writers could create web content through friendly interfaces. Real-time collaboration became possible. Comment systems and user management flourished.

But this convenience came with a hidden cost: the semantic structure that made the static era’s documentation so robust was abstracted away. Instead of marking up a code block as <code class="language-python">, writers were clicking formatting buttons that generated whatever HTML the content management system decided was appropriate.

The Hybrid Renaissance (2010s-present): Static site generators represent the web’s attempt to reclaim the benefits of both eras. They preserve the semantic precision and longevity of hand-crafted HTML while automating the technical complexity that made the static era inaccessible. Writers work in markdown – focusing on content structure rather than presentation – while sophisticated build systems handle the conversion to optimized HTML.

This historical context explains why my copy-paste workflow failed so systematically. I was trying to bridge two different evolutionary stages of web publishing, transferring content from a system that understood semantic structure (VS Code’s markdown processor) to one that prioritized visual consistency over structural integrity (Medium’s dynamic CMS).

The Fundamental Divide: Dynamic vs Static

My research began with a simple question: How do different blogging platforms actually work under the hood? As hinted earlier, the answer revealed a fundamental architectural divide that explains almost everything about modern web publishing.

Traditional platforms like WordPress operate on dynamic architecture – when someone visits your blog post, the server receives their request, queries a database for your content, processes it through various formatting engines, applies your theme, and then assembles the final HTML page in real-time. This happens for every single visitor, every single page view.

This dynamic approach enables powerful features – real-time comments, user accounts, content management interfaces, and plugin ecosystems. But it also creates the exact problems I was experiencing. When I copied content from VS Code to Medium, I was essentially asking Medium’s content management system to reverse-engineer my markdown, store it in their database format, and then reconstruct it using their rendering engine.

Static site generators work completely differently – they take your content and generate all the HTML pages upfront, during the build process. When someone visits your blog, the server simply serves pre-built files. No database queries, no real-time processing, no complex formatting engines running on every page load.

This architectural difference explains everything. In VS Code, I was previewing what my content would look like after proper markdown processing. In Medium, I was feeding my content into a completely different system that had its own ideas about formatting, structure, and presentation.

The Copy-Paste Catastrophe Explained

Now the formatting disasters made perfect sense. When I copied rendered content from VS Code and pasted it into Medium, I wasn’t transferring the underlying markdown structure – I was transferring the visual appearance as interpreted by my clipboard.

Here’s what actually happened during my copy-paste workflow:

1. VS Code rendered my markdown using its built-in processor, creating beautiful HTML with proper heading hierarchy, syntax highlighting, and clean typography
2. My clipboard captured the visual formatting – but not the semantic structure that created it
3. Medium’s editor received formatting instructions – bold text, font sizes, color codes – without understanding that ## heading was supposed to be a second-level header or that python was a language identifier
4. Medium tried to reverse-engineer my intent – converting visual formatting back into its own content structure, losing semantic meaning in the process

The mathematical equations were the worst victims. LaTeX notation like $$\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}$$ has semantic meaning – it represents a mathematical integral with specific bounds and variables. But when rendered and copied, it became just a collection of symbols that Medium couldn’t interpret.

Code blocks suffered similarly. The syntax highlighting I saw in VS Code wasn’t just colors – it was semantic markup identifying keywords, strings, and functions. When copied as visual formatting, all that semantic information was lost.

The Static Site Generator Revelation

Static site generators solve this problem elegantly because they work with the same source format I was already using. Instead of copying and pasting between different systems, I could write in markdown and have the final website generated directly from that markdown.

The conceptual process is beautifully simple:

1. Write content in markdown – the same format I was already using in VS Code
2. Define site structure and styling – through configuration files and templates
3. Run the generator – which processes all content and creates a complete website
4. Deploy the generated site – upload static files to any web server

No more translation between formats. No more manual formatting corrections. No more fighting with content management systems that had different ideas about how my content should look.

Discovering Hugo

When I started researching static site generators, I was overwhelmed by options. Jekyll, Gatsby, Next.js, Hugo, Eleventy – each with different philosophies and technical approaches. But Hugo stood out for reasons that aligned perfectly with my priorities.

Hugo is built for speed – both in terms of build times and learning curve. While Jekyll requires learning Ruby and Liquid templating, Hugo uses Go templates and can be installed as a single binary. No dependency management, no version conflicts, no complex setup procedures.

Hugo handles my content requirements natively:

• Markdown processing with extensions for tables, footnotes, and task lists
• Syntax highlighting for dozens of programming languages
• Mathematical notation through MathJax or KaTeX integration
• Mermaid diagrams processed during build time
• Content organization with taxonomies, sections, and custom frontmatter

But what really sold me was Hugo’s approach to content management. Instead of fighting with database schemas or plugin architectures, I could organize my content exactly how my brain works – files in folders, with clear naming conventions and logical hierarchies.

Modern Git-Based Deployment

Choosing a static site generator was only half the battle. I still needed hosting that could handle my requirements without introducing new complexities. Traditional web hosting required FTP uploads, server configuration, and ongoing maintenance – exactly the kind of infrastructure overhead I was trying to avoid.

Modern deployment platforms like Netlify, Vercel, and GitHub Pages changed the entire paradigm. Instead of thinking about servers and file transfers, I could connect my content repository directly to a hosting platform. Every time I pushed new content to Git, the platform would automatically rebuild and deploy my site.

The workflow became beautifully simple:

1. Write a new post in markdown using VS Code
2. Commit to Git – the same version control I use for everything else
3. Push to repository – usually GitHub or GitLab
4. Platform automatically builds and deploys – no manual intervention required

This Git-based workflow solved multiple problems simultaneously. Version control for all content, automated backups, the ability to write offline, and deployment that happens without my involvement.

The Technical Elegance

What struck me most about this architecture was how it aligned with software engineering best practices I was already using for code. Instead of maintaining separate workflows for development and writing, I could finally use the same tools and processes for both.

Version control – Every blog post, every configuration change, every template modification is tracked in Git. I can see exactly what changed when, revert problematic updates, and maintain complete history of my content evolution. The same Git repositories that house my research code can also contain the blog posts that explain it.

Separation of concerns – Content (markdown files), presentation (templates and CSS), and deployment (configuration) are cleanly separated. I can redesign my site without touching content, or write new posts without worrying about styling – exactly like separating business logic from presentation layers in application development.

Automated testing – Modern deployment platforms can run build previews for every change, letting me see exactly how updates will look before they go live. No more “publish and pray” workflows. The same continuous integration mindset I use for code now applies to content.

Performance optimization – Static files load faster than dynamic pages, require less server resources, and can be cached aggressively. My complex technical posts with mathematical notation and code examples would actually load faster than simple text posts on dynamic platforms.

Unified development environment – I was already living in VS Code for Python development, data analysis, and technical documentation. Now I could write blog posts in the same editor, using the same extensions, with the same keyboard shortcuts and productivity workflows I’d optimized over years of programming.

The Philosophical Shift

This technical journey revealed something deeper about my relationship with digital tools. For years, I had been adapting my thinking to platform limitations instead of finding platforms that amplified my natural thought processes.

Dynamic platforms optimized for content management – they excel at helping multiple authors collaborate, managing user accounts, and providing friendly interfaces for people uncomfortable with technical tools. But they introduce layers of abstraction between your ideas and their final presentation.

Static site generators optimize for content creation – they assume you’re comfortable with plain text, version control, and command-line tools. In exchange, they give you direct control over every aspect of how your ideas are presented.

The choice between these approaches isn’t just technical – it’s philosophical. Do you want tools that manage complexity for you, or tools that give you the power to manage complexity yourself?

The Lightbulb Moment

The breakthrough came when I realized that my formatting problems weren’t bugs – they were features. Medium’s editor was working exactly as designed, optimizing for ease of use and visual consistency across millions of posts. My mathematical equations and complex code examples were edge cases that fell outside their target use case.

Static site generators flip this equation. Complex technical content isn’t an edge case – it’s the primary use case. Mathematical notation, syntax highlighting, and semantic markup aren’t afterthoughts – they’re core features.

I wasn’t dealing with a platform problem – I was dealing with a platform-content mismatch. My technical writing needed tools designed for technical writing.

The Path Forward

Understanding this architectural difference clarified my entire approach to technical writing. Instead of fighting with platforms that were designed for different use cases, I could choose tools that were built specifically for the kind of content I wanted to create.

Hugo + modern deployment platforms wasn’t just a better blogging platform – it was a better thinking platform. A system that would amplify my natural writing process instead of constraining it.

But knowing what I wanted to build and actually building it were two different challenges. The technical concepts were clear, but the implementation details – configuring Hugo, designing templates, setting up deployment pipelines – remained mysterious.

In the next episode, I’ll walk through the actual journey of building this publishing system from scratch. The victories, the frustrations, and the surprising discoveries that came from finally having complete control over how my ideas reach the world.

The architecture was sound. Now it was time to build.