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

~/Blogs/myblog/posts/
edit anything, then save
[folderblog] watching ~/Blogs
yourname.github.io/myblog/
My Blog

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

    Write

    Any editor, plain Markdown, saved into ~/Blogs/myblog/posts/. Images can sit beside the post.

  2. 2

    Save

    The background service notices, waits for the burst of saves to settle, and builds the site in a fresh folder.

  3. 3

    It's live

    If every page rendered, it's published: to GitHub Pages, any git branch, or any command like rsync.

posts/why-i-keep-a-notebook.md
# 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…
Title“Why I keep a paper notebook”from the first heading, which is removed from the body
Address/2026/09/why-i-keep-a-notebook/from the file name (a date prefix sets the date)
Datethe moment folderblog first saw itrecorded once in dates.toml, so editing, syncing or copying never moves it
Front matteroptionaladd title, date, tags or any key your theme wants

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

default theme
The same blog rendered by the Default theme
Ships with every new blogPlain, readable, good typography, light and dark. Yours to change: the whole theme is copied into the blog.
text-only theme
The same blog rendered by the Text-only theme
Agent 1 · “a text-only minimalist site”Monospace, no colour, no images: photos become numbered plates described in text, via a four-line image override.
magazine theme
The same blog rendered by the Magazine theme
Agent 2 · “a dense magazine with tag pages and search”A lead story, cover tiles, section pages per tag and series, paginated archives, and client-side search from a JSON index the theme generates.
film strip theme
The same blog rendered by the Film strip theme
Agent 3 · “a single-page horizontal scroller”The whole blog on one sideways reel. Every post URL still exists and deep-links into its frame; photo posts become filmstrips.
theme/tags/tag.html: one template, a page per tag
{#---
each = "tags"
url  = "/tags/{{ item.slug }}/"
---#}
{% extends "_layouts/base.html" %}
{% block main %}
  <h1>#{{ item.name }}</h1>
  {% for post in item.posts %} …
Check your work, or let your agent do it
❯ 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.

  1. Register a small GitHub App on your own account: Administration, Contents and Pages set to read and write, with Device Flow on.
  2. Install it on your account, for All repositories (folderblog creates a new repository for each blog).
  3. Log in with folderblog login github and a one-time code.
  4. That's it. folderblog new myblog creates 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…

Write a file. Save it.
That's publishing.