Markdown for Bloggers: A Complete Workflow

Blogging in Markdown gives you three things a WYSIWYG editor can't: your words as files you own, version control that tracks the evolution of your writing, and portability across every platform that renders Markdown. The tradeoff is setting up the workflow — but once it's running, drafting to publishing is faster than any web editor.

This guide covers a complete workflow, from "I have an idea" to "it's live and indexed by Google." Tool-agnostic, but concrete examples where they matter.

The workflow overview

Five phases:

1. Capture — idea → draft file
2. Draft — rough content → first readable version
3. Polish — first version → publishable
4. Publish — push to live site
5. Distribute — cross-post, newsletter, social

Each phase is faster in Markdown than in WYSIWYG platforms because the friction between "I have an idea" and "it's a file on disk" is near-zero.

Phase 1: Capture

The single biggest predictor of whether a blog stays alive is whether ideas make it out of your head before they evaporate.

Setup:

• One folder: ~/writing/drafts/
• One file naming convention: YYYY-MM-DD-slug.md or ideas.md (a single rolling file for half-thoughts)
• One capture shortcut in your editor

Capture template:

---
title: "Working title — will change"
slug: "working-slug"
date: 2026-03-25
status: idea
tags: []
---

# Working title

## Why this post exists

One sentence: what problem does this post solve for the reader?

## Who it's for

One sentence: who's the specific reader?

## Key points

- ...
- ...
- ...

## Sources / research

- ...

That's the entire capture template. No fancy structure. The important fields are "why this post exists" and "who it's for" — ideas that can't answer both questions usually shouldn't be posts.

Capture hygiene:

• Once a week, review idea files. Promote to drafts/ folder the ones that still feel alive. Delete the ones that don't.
• Don't worry about quality at capture. A bad idea captured is better than a good idea forgotten.

Phase 2: Draft

Drafting is where Markdown shines. You're not fighting a toolbar — you're just writing.

Structure-first drafting:

1. Write the H2 section headings first. Arrange them in the order that makes sense.
2. Under each heading, drop 2–5 bullet points of what you want to say.
3. Convert bullets to prose, one section at a time.
4. Write the intro last. (You don't know what the post is about until you've written it.)

Don't polish while drafting. Fix typos if you see them; leave everything else.

Useful frontmatter during drafting:

---
title: "..."
description: "..."
date: 2026-03-25
status: draft     # idea | draft | review | scheduled | published
tags: []
est_words: 1500
---

The status field lets you filter across your drafts/ folder to see what you're actively working on. The est_words field sets a target — helpful for planning, optional once you have experience.

Length calibration for different post types:

• Quick tip / update: 300–500 words
• How-to / tutorial: 800–1,500 words
• Deep dive / explainer: 1,500–3,000 words
• Pillar / comprehensive guide: 3,000+ words

Write to the length the topic needs, not an arbitrary target. Padded posts are boring.

Phase 3: Polish

The polish phase turns a draft into something worth publishing. Specific passes:

Pass 1: Structure

• Every H2 section earns its place. Cut or merge sections that overlap.
• No H2 has more than ~500 words without sub-headings (H3).
• The intro previews what the post covers. The conclusion doesn't repeat the intro.
• Each section's first sentence tells the reader why the section matters.

Pass 2: Sentences

• Read aloud. Any sentence that trips you up, rewrite.
• Cut adjectives and adverbs ruthlessly. "Very important" is less emphatic than "important."
• Kill hedging. "I think this might be useful" → "this is useful" or cut entirely.
• Replace filler phrases: "at the end of the day," "in today's world," "it's worth noting that."
• Prefer active voice: "The library caches responses" > "Responses are cached by the library."

Pass 3: Examples and code

• Every abstract claim gets a concrete example.
• Code blocks have language hints: ```python not ```.
• Code is copy-paste runnable or clearly labeled as illustrative.
• Screenshots have alt text.
• Images are compressed (see Phase 4).

Pass 4: SEO basics

You're not writing for search engines — you're writing for readers who find you through search engines. Three concrete things:

1. Title: clear, specific, contains the main keyword. "How I Think About Things" is useless; "How to Write a Blog Post in Markdown" wins.
2. Description (frontmatter description): 120–160 characters. Describes the post's value. Shows up in search results and social shares.
3. Headings: use H2/H3 naturally, but include keywords the reader might search.

Don't stuff keywords. Don't write for Google. Write for the reader who might search the exact question your post answers.

Pass 5: FAQ section

Adding a short FAQ (3–5 questions) at the end of a post has two benefits:

• Surfaces answers for readers who skimmed and missed them
• Qualifies your post for FAQPage structured data, which can display as rich results in Google

Pick questions a first-time reader would ask after reading the post, not questions that are covered in the body.

Phase 4: Images and assets

Blogging in Markdown without a plan for images is how blogs die.

Storage conventions

Option A — images next to posts:

posts/
├── 2026-03-25-markdown-workflow/
│   ├── index.md
│   ├── cover.jpg
│   ├── editor-screenshot.png
│   └── diagram.svg

Option B — flat image folder:

posts/
├── 2026-03-25-markdown-workflow.md
images/
├── 2026-03-25-cover.jpg
├── 2026-03-25-editor.png

Option A is cleaner for multi-image posts. Option B is simpler for text-heavy blogs where posts rarely have more than one image.

Optimization

Unoptimized images are the #1 cause of slow blogs. Run every image through:

• JPEG: cjpeg or mozjpeg with quality 80–85
• PNG: oxipng or pngquant
• SVG: svgo
• Everything: add a WebP or AVIF variant for modern browsers

One-liner for batch compression (macOS/Linux with ImageMagick + mozjpeg):

find . -name "*.jpg" -exec mogrify -quality 85 -strip {} \;
find . -name "*.png" -exec pngquant --ext .png --force --quality 70-90 {} \;

A blog post with 1MB of compressed images feels twice as fast as one with 3MB of raw images — same content, different experience.

Alt text

Every image gets alt text. Not optional. Two audiences:

• Screen reader users (accessibility)
• Anyone browsing with images disabled (slow connection, Reader mode)

Write alt text that describes the image's purpose in the post, not just its contents:

• Bad: "Image"
• Bad: "A screenshot"
• Okay: "A screenshot of VS Code"
• Good: "VS Code with the Markdown preview pane open, showing rendered headings and code blocks"

Phase 5: Publish

The publishing step depends on your site setup. Common options:

Static site generators

For Hugo, Jekyll, Eleventy, Astro, Next.js, Gatsby:

1. Move the finalized .md file from drafts/ to the site's content folder.
2. Update frontmatter: status: published, verify date, set draft: false if your SSG uses it.
3. Commit and push. Your CI/CD rebuilds and deploys.

A typical command sequence:

mv ~/writing/drafts/2026-03-25-slug.md ~/sites/myblog/content/posts/
cd ~/sites/myblog
git add content/posts/2026-03-25-slug.md
git commit -m "post: Markdown blogging workflow"
git push

Cloudflare Pages, Netlify, or Vercel picks it up and deploys in a few minutes.

Scheduled publishing

Most SSGs treat posts with future date fields as drafts until the build runs after that date. Pair with a scheduled rebuild (daily cron job or GitHub Actions on a schedule) and you have built-in scheduled publishing:

# .github/workflows/daily-rebuild.yml
on:
  schedule:
    - cron: "0 13 * * *"  # Daily at 13:00 UTC

Previewing

Before publishing: preview locally (hugo serve, npm run dev, etc.) or on a preview branch (Netlify, Vercel, and Cloudflare Pages all auto-deploy preview URLs from PRs). Publishing something with broken links or a malformed table is what the preview is for.

Phase 6: Distribute

Publishing to your site is the start, not the end. A few distribution patterns that don't feel spammy:

Cross-post to other platforms

Medium, Dev.to, Hashnode, and LinkedIn all accept Markdown. Paste your post in, set the canonical URL to your own site's post, and let the platform do its thing. Benefits:

• Your post reaches audiences who won't visit your blog directly
• Canonical URL tells Google your site is the source, avoiding duplicate-content penalties
• You keep control of your content on your own site

Tools: Dev.to has a canonical field in publish settings. Medium has "Import a story from your blog." Hashnode has cross-publishing built in.

Email

If you have a newsletter, send a short version of the post with a link to the full version on your site. Your subscribers are the most engaged audience you have — prioritize them.

Social

A single link-drop tweet is low effort and low reward. Higher-impact options:

• Pull a key insight from the post into a Twitter/X or LinkedIn thread, with a link at the end
• Share a before/after screenshot, code snippet, or diagram from the post
• For Reddit, only post in communities where your content is genuinely on-topic and non-promotional

Don't spam. A post worth reading travels on its own if it reaches the right people.

Maintenance

Published posts aren't frozen. Over time:

• Update posts when information changes. Add updated: 2026-04-15 to frontmatter. Note major changes in a changelog at the bottom.
• Fix broken links. Use lychee or similar in CI to catch rot.
• Retire or merge posts that aren't working. Low-traffic, low-value posts dilute your site's overall authority.
• Republish pillar posts annually. Update examples, refresh the date, re-promote. Search engines treat updated content as fresher.

Common mistakes

• Draft paralysis. Better to ship a B- post than to never ship an A+ post.
• Over-engineering the site. Spend time writing, not tweaking CSS.
• Publishing without images or formatting. A wall of text doesn't convert readers, even if the content is strong.
• Inconsistent tags/categories. Pick 5–10 tags, stick to them, don't add javascript, JavaScript, and JS as three separate tags.
• No archive or search. Older posts should be findable. An /archive/ page listing all posts by date is 10 minutes of work.

Starter stack

If you're starting from zero and want a blog in a weekend:

• Static site generator: Astro (with the Astro Paper theme) or Hugo (with PaperMod)
• Editor: VS Code with the Markdown All-in-One extension (see editors comparison)
• Hosting: Cloudflare Pages or Netlify (free tier, auto-deploys from GitHub)
• Domain: any registrar; Cloudflare's registrar is cheap and clean
• Analytics: Plausible (simple, privacy-friendly) or GA4 (free, powerful)
• Newsletter: Buttondown or ConvertKit — both accept Markdown posts

Total setup time: 4–8 hours for someone comfortable with the command line. Total monthly cost: $0–15 depending on domain and newsletter tier.

Closing

The hardest part of a Markdown blog isn't the tools — it's the writing. Every step of this workflow is designed to remove friction between your brain and a published post. Use the template. Write the draft. Polish once. Ship.

Perfectionism is the enemy of frequency, and frequency is what builds an audience. Your first 50 posts will be worse than your 100th. The only way through is through.