Sebastian Alvarez
Back to Blog

Is Markdown the Best Format for Blogs?

June 15, 2025
By Sebastian Alvarez
Markdown
Blog
Content Strategy
Developer Tools
Developer Experience
Is Markdown the Best Format for Blogs?

Introduction

When building a developer blog, choosing how to store and write your content matters as much as how you display it. After experimenting with JSON, WYSIWYG editors, and headless CMSes, I found Markdown to be the cleanest, most scalable solution.

In this post, I'll explain why I use Markdown to structure my blog content, how it's stored, how it's dynamically rendered in the frontend — and why Markdown solves problems that plain JSON couldn’t.

Why I Store Blog Posts in Markdown

Here’s why Markdown is my go-to format:

1. 🧠 Simple, Human-Readable Syntax

Markdown feels natural to write. Headers, lists, code blocks, and links are quick to type, with zero friction. It's like writing an email with formatting superpowers — no UI lag, no weird HTML artifacts.

2. 🧱 Easy to Store, Version, and Track

Each post in my blog is stored as a simple JavaScript object that includes a Markdown content field. This means I can:

  • Store content in Git (like code)
  • Track changes over time
  • Use pull requests for content reviews
  • Move fast without external tooling

3. 🔄 Dynamic and Flexible Rendering

One major pain point I faced early on was using raw JSON to structure post content. That meant manually defining paragraphs, code blocks, and titles like this:

[
  { "type": "h2", "text": "Introduction" },
  { "type": "p", "text": "This post will cover..." },
  { "type": "code", "language": "js", "text": "const x = 42;" }
]

This quickly became messy and hard to scale. Every post had a slightly different structure, and I found myself writing a custom renderer to deal with all the variations. Markdown solved that instantly.

With Markdown, I can write naturally and let a parser like marked or remark handle the conversion to HTML, cleanly and consistently.

4. ✍️ Developer-First Writing Experience

Since my entire blog is code-based, it makes sense that writing should happen in code too. I can write a new blog post in my code editor, commit it with Git, and deploy. No extra UIs or plugins needed.

How I Use It in My Blog

Here’s what a blog post structure looks like in my setup:

{
  slug: 'mastering-async-javascript',
  title: 'Mastering Asynchronous JavaScript',
  date: 'October 26, 2023',
  excerpt: 'A deep dive into Promises, async/await...',
  content: `## Introduction\nAsynchronous programming is...`,
  author: 'Sebastian Alvarez',
  tags: ['JavaScript', 'Async']
}

The content is raw Markdown. In the frontend, I convert it using marked:

<div
  className="prose dark:prose-invert max-w-none"
  dangerouslySetInnerHTML={{ __html: marked(post.content) }}
/>

This gives me the freedom of Markdown plus full control of rendering.

Styling with Tailwind (Secondary but Nice)

To make the Markdown look good, I use Tailwind’s @tailwindcss/typography plugin. It gives me a prose class that adds consistent styles to elements like <h1>, <p>, <pre>, and more.

Tailwind's utility-based customization lets me tweak the style without touching the HTML. For example:

prose-headings:text-primary
prose-a:text-accent hover:prose-a:text-primary
prose-code:font-code
prose-pre:bg-muted

This means I don’t have to worry about content authors messing up the layout — Markdown handles structure, and Tailwind handles appearance.

Conclusion

Markdown hits the sweet spot for blogging as a developer:

  • Fast to write
  • Easy to maintain
  • Dynamic to render
  • Portable across tech stacks
  • Perfect for Git-based workflows

If you're building a blog or dev-focused site, consider Markdown as your foundation — and let styling be a second step, not the first problem to solve.

More Articles