How to Blog with Markdown: A Publishing Workflow

Blogging in Markdown keeps drafts readable, versionable, and separate from presentation. A practical workflow has six phases: capture, draft, polish, manage assets, publish, and distribute.

Your publishing platform still determines frontmatter fields, raw Markdown support, scheduling, and previews. Test its behavior and use the blog post template as a starting point rather than a fixed schema.

The workflow overview

Six phases:

1. Capture — idea → draft file
2. Draft — rough content → first readable version
3. Polish — first version → publishable
4. Manage assets — prepare images, diagrams, and accessible alternatives
5. Publish — push to live site
6. Distribute — cross-post, newsletter, social

Markdown keeps each phase in a source file you can search, diff, and move between compatible tools.

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, add the points and evidence needed to answer that part of the topic.
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: answer one narrow question.
• How-to / tutorial: include prerequisites, ordered steps, and verification.
• Deep dive / explainer: build the concept with evidence and examples.
• Reference guide: optimize for scanning and retrieval.

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.
• Add H3 headings when they make a long section easier to scan.
• The intro answers the search intent; the ending gives a useful next step rather than repeating it.
• 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): summarize the page concisely. Search engines may use it as a snippet or choose other page text.
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

Add a short FAQ only when visible questions answer genuine follow-up intent:

• Surfaces answers for readers who skimmed and missed them
• Can pair with valid FAQPage structured data when all questions and answers are visible. Eligibility for Google FAQ rich results is restricted and not guaranteed.

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

Large images are a common performance cost. Choose appropriate dimensions and compression:

• JPEG: cjpeg or mozjpeg; compare quality and file size with representative images
• 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 {} \;

Measure the resulting page on representative devices and connections rather than relying on a fixed size threshold.

Alt text

Informative images need useful alt text; decorative images should use empty alt text. Consider:

• 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

Future-date behavior varies by static site generator and configuration. If yours excludes future posts, pair that documented behavior with a scheduled rebuild and test the timezone:

# .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

Cross-posting platforms differ: some import Markdown, some accept a subset, and some use rich-text editors. Check current import behavior, formatting, links, and canonical controls before publishing. Potential benefits:

• Your post reaches audiences who won't visit your blog directly
• A canonical URL can hint which equivalent page search engines should consolidate
• 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 only when they are obsolete, redundant, or unhelpful. Low traffic alone does not make a useful niche reference expendable.
• Update posts when facts or reader needs change. Preserve the original publication date and record substantive updates honestly.

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. Maintain a controlled vocabulary; do not create javascript, JavaScript, and JS as 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: a provider that supports your build and preview workflow
• Domain: any reputable registrar with the controls you need
• Analytics: an option that matches your measurement and privacy requirements
• Newsletter: a provider whose current editor and import flow fit your source format

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.