folderblog 0.2.11 · free & open source
A folder
is a blog.
Write a Markdown file. Save it into a folder. A few seconds later it's live on your site. No front matter, no build step, no deploy command. Nothing to remember, so nothing to forget.
Linux · GitHub Pages or any host · themes designed by you, or your coding agent
[folderblog] watching ~/Blogs
Nothing published yet. Press Save.
The tour
Everything in three and a half minutes
Narrated, captioned, and every site in it is real.
How it works
Write. Save. That's publishing.
- 1
Write
Any editor, plain Markdown, saved into
~/Blogs/myblog/posts/. Images can sit beside the post. - 2
Save
The background service notices, waits for the burst of saves to settle, and builds the site in a fresh folder.
- 3
It's live
If every page rendered, it's published: to GitHub Pages, any git branch, or any command like rsync.
# Why I keep a paper notebook
Every few years I try to go fully
digital, and every few years I end
up back at a cheap A5 notebook…
dates.toml, so editing, syncing or copying never moves itWhat you get
Small engine, big guarantees
Just write
Plain Markdown. No front matter: the title comes from your first heading, the address from the file name, the date from when folderblog first saw it.
Live in seconds
A background service watches your folder, debounces bursts of saves, ignores editor temp files, and publishes when something changes.
GitHub Pages, zero clicks
Log in once. After that, a new blog creates its own repository and turns on Pages at the first publish.
Never half-broken
Every build happens in a fresh folder and replaces the live site only if everything rendered. A broken template changes nothing.
Tells you when it fails
A desktop notification with the file and line, folderblog status, and the journal. Expired logins too: pending posts publish once you log back in.
Many blogs, one folder
Every folder in ~/Blogs is its own blog, with its own theme, settings and host. One breaking never touches the others.
A gallery, if you want one
folderblog gallery on, then drop pictures into a folder. Subfolders become albums, a note beside a photo adds a caption and tags, and only resized copies go online.
Themes with no limits
Jinja templates that own every byte: any layout, JSON search indexes, templated CSS, SVG, a page per tag or year or series.
Made for coding agents
Every blog ships an AGENTS.md contract, plus preview, check, data and stress fixtures, so an agent can design and verify on its own. folderblog mcp lets one put up podcast episodes too, publishing only after you say yes.
A podcast, if you want one
folderblog podcast on, then one folder per episode with its MP3 or MP4. Show and episode pages with a player, and a feed ready for Apple Podcasts and Podcasting 2.0. The audio lives on Cloudflare R2, set up step by step with folderblog podcast setup.
Templates to fill in
Every blog has a templates/ folder: a sample post and a sample episode with every field explained. Copy one, fill it in, delete what you don’t need.
Updates bring the new parts
Install a new version and restart the service. Each blog gets what the new version adds, like the templates, and nothing of yours is changed.
Theming
The engine owns your content.
The theme owns every other byte.
folderblog finds your posts, renders Markdown, builds the RSS feed and sitemap, and never slips its own markup into your pages. A theme is a folder of Jinja templates that can produce any layout and any file: pages, a search index, a stylesheet, an image.
To prove it, we gave three coding agents the same blog, its AGENTS.md, and a one-line brief each. None of them needed a change to the engine.




{#--- each = "tags" url = "/tags/{{ item.slug }}/" ---#} {% extends "_layouts/base.html" %} {% block main %} <h1>#{{ item.name }}</h1> {% for post in item.posts %} …
❯ folderblog preview --fixtures stress ❯ folderblog check ok: 37 files rendered, feed valid, no broken internal links ❯ folderblog data /2026/09/hello/ { "post": { "title": "Hello", … } }
GitHub Pages
Five minutes once. Zero clicks after.
- Register a small GitHub App on your own account: Administration, Contents and Pages set to read and write, with Device Flow on.
- Install it on your account, for All repositories (folderblog creates a new repository for each blog).
- Log in with
folderblog login githuband a one-time code. - That's it.
folderblog new myblogcreates the repository and turns on Pages at the first publish.
Logins renew themselves. If one expires or is revoked you get a notification, and anything waiting is published within five minutes of logging back in. Step-by-step guide →
Install
One static binary. git is the only dependency.
curl -LO https://github.com/ninepointlabs/folderblog/releases/download/v0.2.11/folderblog-bin-0.2.11-1-x86_64.pkg.tar.zst sudo pacman -U folderblog-bin-0.2.11-1-x86_64.pkg.tar.zst
curl -LO https://github.com/ninepointlabs/folderblog/releases/download/v0.2.11/folderblog_0.2.11-1_amd64.deb sudo apt install ./folderblog_0.2.11-1_amd64.deb
sudo dnf install https://github.com/ninepointlabs/folderblog/releases/download/v0.2.11/folderblog-0.2.11-1.x86_64.rpm
curl -L https://github.com/ninepointlabs/folderblog/releases/download/v0.2.11/folderblog-0.2.11-x86_64-linux.tar.gz | tar xz sudo install -m755 folderblog-0.2.11-x86_64-linux/folderblog /usr/local/bin/
cargo install --git https://github.com/ninepointlabs/folderblog --tag v0.2.11
Then:
❯ folderblog login github --client-id Iv23li… # once: see the guide ❯ folderblog install-service ❯ folderblog new myblog ❯ echo "# Hello" > ~/Blogs/myblog/posts/hello.md
These commands install 0.2.11. Updating later: install the new release's package the same way (its file names are on the releases page), then
❯ systemctl --user restart folderblog # your blogs pick up what's new
Questions
Good questions
Does folderblog ever change my files?
Never your posts or pages, so an editor with the file open never complains. Its own state (the last good build, caches) lives in a hidden .blog/ folder. The only other files it writes by itself are ones it owns: dates.toml (when it first saw each undated post), the generated part of AGENTS.md, and sample files in templates/ that it adds once and never puts back if you delete them.
Can I run a podcast with it?
Yes. folderblog podcast on, then one folder per episode in podcast/ with its MP3 (or MP4 for video) and show notes. folderblog makes the show and episode pages and a feed for Apple Podcasts, Spotify and the rest. The audio goes to Cloudflare R2, which folderblog podcast setup connects step by step, and the site waits until the upload has worked, so the feed never points at a missing file. An agent can do it all for you through folderblog mcp, and publishes only after you say yes.
Which details can I put at the top of a post?
None are needed. To fill some in by hand, copy templates/post.md (or templates/podcast-episode/ for an episode) from your blog folder: it has every field folderblog knows, each with a short note.
What happens if I break something?
The build fails in its fresh folder, the live site stays exactly as it was, and you get a desktop notification with the file and line. folderblog status shows it too. Fix it and the next save publishes.
Do I have to use GitHub?
No. Any git remote works, and so does any command: rsync, rclone, Cloudflare's wrangler, the Netlify CLI. folderblog runs it with the finished site folder.
Can I use my own domain?
Yes. folderblog new example.com --domain example.com sets it up on GitHub Pages and prints the DNS records to add at your registrar.
Comments, analytics, search?
Visitor counts are built in but off by default: two lines in blog.toml turn on cookie-free GoatCounter. Comments and search aren't, on purpose. The theme owns every byte, so a theme can add them. The magazine theme above generates its own search index.
macOS or Windows?
Linux for now: packages for Arch, Debian/Ubuntu and Fedora, plus a static x86_64 binary. It's written in Rust, so other platforms are possible.
From the blog
Posts ordered by date and timefolderblog 0.2.11: posts are ordered by date and time, so several posts on the same day show up in the right order. A real podcast on folderblog: My Azeroth LifeA real podcast made with folderblog: My Azeroth Life turns World of Warcraft play sessions into blog posts and narrated episodes, all from one blog folder. Podcasts, templates to fill in, and updates that bring the new partsfolderblog 0.2.6 and 0.2.7: a podcast is now one more folder in your blog, every blog gets templates to fill in, and updates bring the new parts to…