Markdown blog post template with front matter
Open in the editor Opens as blog-post.md, ready to edit. Nothing is uploaded.
The shape of it — edit here, or open the full template
Result
Runs entirely in this tab. Open the full editor to work on a real document.
A post structure that survives contact with an actual reader — most of whom arrived from a search, want one specific thing, and will leave the moment they suspect you are going to make them work for it.
Front matter first
The block between the triple dashes is metadata, not content:
---
title: "The title, written as the thing a reader would search for"
description: "One sentence, under 160 characters, that earns the click."
date: 2026-08-01
tags: [engineering, performance]
draft: true
---
Your generator reads it and strips it. draft: true is worth keeping in the
template: it is a one-word switch that stops a half-finished post publishing
itself, and it is easy to forget to add later.
Watch the colons. A title containing : breaks the parse unless it is quoted,
which is why every string value here is in quotes.
Open with the answer
The instinct is to build to the conclusion. The reader’s instinct is to leave before you arrive. Put the finding in the first two sentences and spend the rest of the post justifying it — you lose nothing, because the people who want the reasoning keep reading, and you keep the people who only wanted the answer.
The failed attempt is the valuable part
The section most often cut is “what I tried first”, and it is the one most worth keeping: your reader is usually about to try exactly that. Say what you expected, what happened instead, and why the two differed.
Show the numbers
| Metric | Before | After |
|---|---|---|
| Render time | 4.1 s | 1.6 s |
| Bundle size | 480 KB | 190 KB |
Right-align numeric columns so the digits line up and the comparison is visible without reading. Two rows of real measurements do more for credibility than any amount of adjective.
Close with what you would change
Short, specific, and honest about the limits of what you did. It is disproportionately the section people quote when they share the post — and the one that makes the difference between a write-up and an advert.
Common questions
- What is the block at the top between the three dashes?
- YAML front matter — metadata for whatever builds your site, not part of the post. Static site generators read the title, date and tags from it and never render it. The editor here hides it in the preview and marks it with a small note, so you can see it is being recognised.
- Which front matter fields do I actually need?
- Almost always title and date; usually description and tags; sometimes draft. The exact set depends on your generator — Hugo, Astro, Jekyll and Eleventy each define their own — so check its docs before adding fields it will ignore.
- Should the post start with an H1 if the title is already in the front matter?
- Usually not. Most generators render the front matter title as the page's H1, so a second one in the body gives you two, which is a real accessibility and SEO problem. This template includes it for drafting; delete it if your layout supplies one.
- Why open with the conclusion?
- Because that is the order people read in. Most visitors arrived from a search with a specific question, and a paragraph of context before the answer reads as an obstacle. The reasoning still gets read — by the people who wanted it, after they have the answer.
- How do I write the code examples?
- Fenced blocks with the language named after the opening backticks, which is what turns on syntax highlighting. Keep them short enough to read on a phone: about ten lines and sixty characters wide before horizontal scrolling starts.
- Can I preview it before it goes into my site?
- Yes, and it is worth doing. Paste the draft into the editor here and the preview renders it the way a Markdown-based generator will, front matter and all, without running a build.