2 min read
Writing in Markdown, publishing with git
How a post goes from a text file to the live site, including drafts, images, and fixing a typo from a phone.
The workflow for this blog fits on an index card: write a Markdown file, commit it, push it. A build server does the rest. Here is what each step looks like in practice, and the few habits that keep it smooth.
One file per post
Each post is a file in src/posts/. The file name becomes the address, so markdown-and-git.md is published at /posts/markdown-and-git/. Pick the name with care, because changing it later breaks links.
At the top of the file is a short block called front matter:
---
title: Writing in Markdown, publishing with git
description: How a post goes from a text file to the live site.
date: 2026-09-23
tags: [writing, workflow]
---
The title and description show up in the post list, in search results and in the feed. The date sets the order. Tags group posts on the tags page. Everything below the second --- is the post itself.
Drafts
A draft is a post that is not ready to be seen. The simplest way to keep one is a git branch: write on a branch called draft-whatever, and merge it when it is done. The live site is built from the main branch only, so nothing leaks.
If you prefer to keep drafts next to the finished posts, add draft: true to the front matter and tell Eleventy to skip those files in production. Either way works. The branch is harder to publish by mistake.
Images
Put images next to the post or in one images folder, and keep them small. A photo straight from a phone is often 4 MB. Resized to 1600 pixels wide and saved as WebP or a compressed JPEG, it is closer to 200 KB and looks the same on screen. Always write alt text that says what the image shows, not what it is called.
Publishing
When the post is ready, commit it and push:
git add src/posts/markdown-and-git.md
git commit -m "Post: writing in Markdown"
git push
The push starts a build on the host. On GitHub Pages that is a workflow file in .github/workflows/. Netlify, Vercel and Cloudflare Pages watch the repository and build on their own. A minute later the post is live.
Fixing a typo from a phone
Because the posts are text files on GitHub, you can edit one in the GitHub web editor or app, commit there, and the same build runs. This is the feature I did not expect to use and now use every week.
Keep the habits small
Write the description before the post; it forces you to know what the post is about. Read the post once in the browser before you push, since Markdown hides some mistakes until it is rendered. And commit often. A git history is the best undo button a writer has ever had.