A personal journey from platform acceptance to technical rebellion
(source: The Unquestioned Years
A decade ago, I lived in blissful ignorance of better alternatives. Windows was my operating system, Microsoft Office was my document suite, and whatever blog platform provided was my publishing tool. I wrote movie reviews, game critiques, and random thoughts about life – mostly text with occasional images. The web editors worked fine because my needs were simple.
I never questioned these choices, just like I never questioned why I wake up my machines from suspend the way I did or which orders I read books. They were simply the tools available, and they seemed adequate for the task.
Looking back, that acceptance feels almost quaint.
The Markdown Awakening
Everything started changing a few years ago when I discovered markdown. What began as a curiosity – “Why do developers prefer this plain text formatting?” – gradually became a complete paradigm shift in how I approached documentation.
Markdown’s simplicity was seductive. Instead of fighting with formatting menus and style inconsistencies, I could focus purely on content structure. Headers were #, emphasis was *, code was backticks. The syntax mapped directly to how I thought about organizing information.
Within months, I had abandoned Microsoft Office entirely. Every document, every note, every technical specification was written in markdown. VS Code became my universal editor – equally comfortable with Python scripts, LaTeX documents, and plain text writing. The built-in markdown preview renderer was, honestly, better than most dedicated word processors for the kind of technical documentation I was creating.
This shift changed my entire relationship with digital tools. Instead of adapting my thinking to software limitations, I was using tools that amplified my natural writing process.
The Technical Blog Transition
Last summer, I made the leap into technical blogging on Medium. The context was entirely different from my earlier writing – instead of movie reviews and personal reflections, I was diving deep into AI research, statistical methods, and complex system architectures.
My posts began featuring elements I’d never needed before:
- Mathematical formulations explaining Bayesian inference
- Multi-language code snippets comparing Python and Rust implementations
- Complex diagrams illustrating algorithm workflows
- Statistical equations that needed precise typographical representation
Looking back, Medium never actually “worked perfectly” – I’d just accepted the manual formatting work as part of the blogging process. When I was writing movie reviews or personal reflections, the hour spent fixing formatting after copy-pasting felt like a normal tax on publishing. I assumed that’s just how blogging worked.
But as I dove deeper into computer science and technical writing, my standards changed. I started thinking like a developer about efficiency, automation, and tool optimization. The manual formatting work that I’d previously accepted as inevitable began feeling like a symptom of using the wrong tool for the job.
The Copy-Paste Workflow from Hell
My publishing process evolved into an increasingly frustrating ritual:
- Draft everything in VS Code using markdown (because that’s where I was most productive)
- Preview using the built-in renderer (which handled everything beautifully)
- Copy the rendered content
- Paste into Medium’s editor
- Spend the next hour fixing everything that broke
That final step became my nemesis. What looked perfect in VS Code’s preview turned into a formatting disaster in Medium:
Headings would lose their hierarchy – my carefully structured ## and ### headers would flatten into inconsistent sizes, destroying the logical flow of complex explanations.
Code snippets became unreliable – syntax highlighting would disappear, indentation would collapse, and sometimes entire code blocks would render as plain text. When you’re explaining the difference between Python’s async/await and Rust’s tokio implementations, losing syntax highlighting isn’t just aesthetic – it actively harms comprehension.
Mathematical equations were the worst offender – Medium simply couldn’t handle LaTeX notation. For every formula like $$\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}$$, I had to:
- Navigate a random online LaTeX renderer
- Generate a PNG image of the equation
- Download and upload it to Medium
- Hope it displayed at the right resolution across devices
Mermaid diagrams suffered the same fate – my carefully crafted flowcharts showing algorithm decision trees or system architectures had to be converted to static images, losing their semantic meaning and becoming impossible to modify later.
The manual correction process consumed 60-70% of my publishing time. I was spending more time fighting with the platform than writing content.
The White Paper Standard
As my technical writing became more sophisticated, I started thinking about a simple benchmark: Could I publish an academic white paper with this system?
A proper technical document needs:
- Hierarchical structure with consistent heading styles
- Inline and block mathematical notation that renders beautifully
- Syntax-highlighted code examples in multiple languages
- Complex diagrams that can be modified and updated
- Citations and cross-references that work reliably
- Professional typography that enhances rather than distracts from content
Medium failed this test completely. WordPress with plugins came closer, but required constant maintenance and fighting with conflicting extensions. LaTeX could handle the math and typography but was hostile to web publishing and modern content workflows.
I needed something that combined the writing experience of VS Code markdown with the publishing power of professional typesetting systems.
The Frustration Reaches Critical Mass
The breaking point came during my most recent post about Markov models for Alzheimer’s disease progression. The content required:
- Complex state transition equations
- Python and Rust code comparisons
- Flowcharts showing patient journey modeling
- Statistical formulations for transition probabilities
In VS Code, the post was beautiful – equations rendered perfectly, code was clearly highlighted, diagrams were interactive and informative. It represented exactly the kind of technical communication I wanted to share with the world.
Then I began the copy-paste process.
Two hours later, I had a mangled version on Medium where:
- Mathematical notation had become a collection of awkwardly-sized image files
- Code had lost all meaningful formatting
- Diagrams were static screenshots that conveyed none of their original clarity
- The logical flow of the argument was broken by formatting inconsistencies
I published it because I’d invested too much time to abandon the post entirely. But I knew this workflow was unsustainable.
Why did content that looked perfect in VS Code’s markdown preview turn into a formatting disaster in Medium? What was fundamentally different about how these systems processed the same content? These questions would lead me down a fascinating rabbit hole about web rendering, content management philosophies, and the hidden complexities of what seems like simple copy-paste operations.
The Search for Something Better
That night, I opened a new document in VS Code and wrote down my requirements:
Non-negotiable features:
- Native markdown support (not “markdown compatibility”)
- LaTeX math rendering without image conversion
- Multi-language syntax highlighting
- Mermaid diagram support
- Professional typography
- Fast loading times
- Zero ongoing maintenance
Workflow requirements:
- Write in VS Code (or any markdown editor)
- Preview locally with full fidelity
- Publish with a single command
- No copy-paste formatting fixes
- Version control for everything
Economic constraints:
- Financially free or very low cost
- No vendor lock-in
- Own my content completely
After some initial research, Github Pages & Jekyll and Hugo & Netlify remained in my shortlist.
In fact, I seriously considered GitHub Pages with Jekyll – it had obvious appeal for technical blogging. Free hosting, Git-based workflow, and tight integration with repositories where my code already lived. Many of my colleagues run excellent technical blogs on this stack, and the developer-centric approach aligned with how I was already thinking about content management.
Jekyll’s templating system could handle my markdown content beautifully, and the GitHub Pages deployment pipeline would eliminate the hosting complexity I was trying to avoid. For a technical writer coming from a development background, it seemed like the natural choice.
But as I dug deeper into Jekyll’s ecosystem and GitHub Pages’ constraints, I realized the time investment would be substantial. Jekyll requires learning Ruby, Liquid templating, and a specific plugin architecture. While powerful, it felt like learning a new programming framework just to publish blog posts. GitHub Pages also restricts which Jekyll plugins you can use, potentially limiting future flexibility.
More importantly, I was optimizing for long-term writing productivity, not just technical elegance. Hugo’s Go-based architecture promised faster build times and simpler deployment options. Netlify’s deployment pipeline offered more flexibility than GitHub Pages’ constraints, with features like branch previews and edge functions that might prove valuable as my content strategy evolved.
The deciding factor was maintenance overhead. Jekyll sites require ongoing dependency management – Ruby gems, plugin updates, and compatibility issues that could interrupt my writing flow. Hugo’s single-binary approach and Netlify’s managed deployment promised less time spent on infrastructure and more time spent on content.
GitHub Pages + Jekyll remains an excellent choice for developer-focused technical blogs, especially those closely tied to code repositories. But for my use case – long-form technical writing that happens to include code rather than documentation of existing projects – Hugo + Netlify felt like the better long-term investment.
The Decision: Strategic Platform Separation
After researching static site generators, headless content management systems (aka CMS), GitHub Pages, and various publishing platforms, I realized I didn’t need to choose just one solution. Instead, I could design a strategic approach:
Hugo + Netlify will be my primary technical dissemination platform – where I can express complex ideas without any constraints. Every equation renders beautifully, every code snippet is properly highlighted, every diagram enhances understanding. This is where the full, uncompromised version of my technical writing lives.
Medium remains my “accessible gateway” – where I’ll publish adapted versions that focus on concepts and insights (i.e., code-light and math-light) rather than implementation details. Think executive summaries for readers who want the ideas without diving into mathematical derivations or code implementations, expecting better accessiblity from broader populations.
In short, my change isn’t abandonment; it’s better framed as evolution. Each platform serves its purpose in a broader communication strategy.
What This Really Means
At its core, this transition represents a fundamental shift in how I think about technical communication. For too long, I’ve been adapting my ideas to platform limitations instead of finding platforms that amplify my natural thinking process.
The tools we use to create and share knowledge shouldn’t constrain the knowledge itself. When I’m explaining why diffusion models might revolutionize text generation, or walking through the mathematics of conditional average treatment effects, I need every available tool – equations, code, diagrams, and clear typography working together seamlessly.
Medium served an important role in my blogging journey, connecting me with precious readers and helping me develop my voice as a technical writer. But I’ve outgrown its constraints, just as I once outgrew Microsoft Word’s limitations for technical documentation.
The Broader Pattern
This transition reflects a broader trend in my relationship with digital tools: moving from acceptance of what’s provided toward intentional selection of what serves my goals.
- From Word to markdown: Choosing structure over formatting
- From Windows to Linux: Choosing control over convenience
- From proprietary to open: Choosing ownership over features
- From platforms to infrastructure: Choosing capability over ease
Each transition required learning new skills and temporarily reduced productivity. But each ultimately enhanced my ability to think clearly and communicate effectively.
The Hugo + Netlify setup I’m building may not be just about better blogging – it’s about aligning my tools with my values and my growing sophistication as a technical communicator.
What Comes Next?
In the coming posts, I’ll dive deep into what I discovered about why my copy-paste workflow failed so spectacularly, how modern static site generators fundamentally differ from traditional content management systems, and the specific technical journey of building a publishing platform that finally works the way my brain does. It’s been a fascinating dive into web architecture, deployment pipelines, and the philosophy of content management.