Skip to content

About

A folder is a blog: save Markdown into a folder and it's published to GitHub Pages (or anywhere) seconds later. Themes designed by coding agents.

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

folderblog

New to folderblog? Start with the step-by-step guide. It explains everything folderblog can do and every command, in plain words. The same guide is built in: run folderblog guide, or man folderblog.

A folder is a blog. Write a Markdown file, save it into a folder, and a few seconds later it is live on your site. No front matter, no build step, no commit, no deploy command.

folderblog is a single binary that runs quietly in the background. It watches ~/Blogs, where every folder is its own blog, and publishes each one to GitHub Pages (or anywhere else) whenever you save. With GitHub, even starting a new blog is one command: folderblog creates the repository and switches on Pages for you.

Website and 3-minute video tour: https://folderblog.ninepointlabs.com (the site is itself a folderblog blog; its source is site/).

It is also built to be designed by coding agents. Every blog ships with an AGENTS.md contract, and a theme is nothing but templates, so an agent can build almost any design without touching the engine.

Features

Writing

  • Plain Markdown files. Front matter is optional: the title comes from the first heading (or the filename), the date from the filename (2026-09-30-my-post.md) or from the moment folderblog first saw the file, and it never changes after that (that moment is kept in dates.toml, so it survives git clones and copies). Several posts on one day stay in the order they were written (see Date below).
  • Folder posts: put index.md and its images in posts/my-trip/ and relative image paths just work.
  • Pages (pages/about.md → /about/), drafts that only appear in preview, a static/ folder copied as-is, and data/ files (JSON, TOML, YAML) for templates.
  • Tables, footnotes, task lists, syntax highlighting, and raw HTML are all supported.
  • An optional photo gallery: drop pictures into gallery/, folders become albums, and a small .md beside a photo adds a title, caption and tags.
  • An optional podcast: one folder per episode in podcast/ (show notes plus an MP3 or MP4), a show page, episode pages with a player, and a feed with iTunes and Podcasting 2.0 tags. Audio is never put in the site or in git: it goes to Cloudflare R2, which folderblog podcast setup connects step by step.
  • An MCP server (folderblog mcp) so an agent can turn an audio file into a draft episode, write its notes and chapters, check it, and publish it once you say yes.
  • A templates/ folder in every blog: a sample post and a sample podcast episode with every front matter field explained, to copy when you want to fill things in by hand.
  • Deleting a file unpublishes it. folderblog never edits your posts or pages.
  • Updating keeps your blogs current: after an update the service adds what the new version brings (like templates/) and refreshes AGENTS.md, without touching anything of yours.

Publishing

  • Saves are debounced, and editor temp and swap files are ignored.
  • GitHub Pages with no manual steps: repo creation, Pages setup, custom domains and HTTPS are handled for you.
  • Also publishes to any git branch or runs any command (rsync, rclone, wrangler…).
  • Each blog is independent: its own theme, settings and host, and a problem in one never affects the others.

Safety and visibility

  • Every build happens in a fresh folder and only replaces the live site if everything succeeded. A broken template never takes your site down or half-updates it.
  • Desktop notifications, folderblog status, and the systemd journal tell you when something fails. You also hear about it if your GitHub login expires, and anything waiting publishes on its own once you fix it.

Design

  • Themes are Jinja templates (minijinja), with no hidden base theme.
  • Any output format: HTML, JSON search indexes, templated CSS, SVG, extra feeds.
  • One template can render many pages: tag pages, year archives, series and paginated lists.
  • Per-post layouts, overridable Markdown markup, a full data model, and hand-built HTML pages.
  • The RSS feed and sitemap are generated by the engine, so no theme can break them, plus a robots.txt that points at the sitemap (unless you add your own).
  • Search and link-preview tags out of the box: the default theme gives every page a description, canonical link, OpenGraph and Twitter card tags, and posts BlogPosting JSON-LD and their own share image.
  • Optional, off by default: cookie-free GoatCounter page counts with two lines in blog.toml (see Analytics).
  • preview with live reload, check (template errors with file:line, feed validation, broken links), data (the exact template context for any URL), and fixture content for testing themes against edge cases.

Install

Packages are on the releases page. They contain a single static binary for x86_64 Linux and a systemd user service. git is the only dependency.

Arch Linux / Omarchy / Manjaro

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

Debian / Ubuntu / Pop!_OS / Mint

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

Fedora / RHEL / openSUSE

sudo dnf install https://github.com/ninepointlabs/folderblog/releases/download/v0.2.11/folderblog-0.2.11-1.x86_64.rpm

Any other Linux (tarball)

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 -Dm755 folderblog-0.2.11-x86_64-linux/folderblog /usr/local/bin/folderblog

With autonomix-cli: autonomix-cli add https://github.com/ninepointlabs/folderblog

From source (Rust 1.89 or newer): cargo install --git https://github.com/ninepointlabs/folderblog --tag v0.2.11 (without --tag you get the newest, unreleased code from main).

These links are for folderblog 0.2.11, so they keep working after newer releases come out. For the newest version, take the same commands from the latest release (the version number is in each file name).

Check it worked: folderblog --version.

Updating: install the new package (or binary) the same way, with the new release's file name, then restart the service: systemctl --user restart folderblog. On its first start with the new version it brings every blog up to date (see Running in the background).

Desktop notifications use notify-send (package libnotify or libnotify-bin), which most desktops already have.

Quick start

To try it on your own machine first, no accounts needed:

folderblog new myblog --no-github
echo "# Hello, world

My first post." > ~/Blogs/myblog/posts/hello.md
folderblog build ~/Blogs/myblog
folderblog preview ~/Blogs/myblog    # open http://127.0.0.1:4000

To publish on GitHub Pages (if you already made myblog above, pick another name in step 3):

# 1. One time: connect GitHub (see "Preparing GitHub" below for the Client ID)
folderblog login github --client-id Iv23li...

# 2. Start the background service
folderblog install-service

# 3. Create a blog. The GitHub repo and Pages are set up automatically.
folderblog new myblog

# 4. Write
echo "# Hello, world

My first post." > ~/Blogs/myblog/posts/hello.md

About a minute later the post is live at https://<your-username>.github.io/myblog/. The first publish of a new blog waits for GitHub's first Pages build, which usually takes 1–2 minutes. Later posts appear within about 30–60 seconds.

To see what is going on: folderblog status.

Not using GitHub? Skip step 1, run folderblog new myblog --no-github, and set a deploy target in ~/Blogs/myblog/blog.toml.

Preparing GitHub

folderblog publishes through a small GitHub App that you register on your own account. It's a one-time, two-minute form. After that folderblog can create repos and switch on Pages by itself, so new blogs need no trips to GitHub.

Why an app of your own? The login belongs to you alone, you choose exactly what it may do, and no third-party service is involved. folderblog talks to GitHub directly from your machine.

1. Register the app

Open https://github.com/settings/apps/new (for an organisation: https://github.com/organizations/<org>/settings/apps/new) and fill in:

Field Value
GitHub App name Anything unique, e.g. folderblog-yourname
Homepage URL Anything, e.g. https://github.com/yourname
Callback URL Leave empty
Expire user authorization tokens ✅ Keep ticked. Logins renew themselves and last about 6 months
Request user authorization (OAuth) during installation Leave unticked
Enable Device Flow ✅ Tick this. It is how folderblog login works
Webhook → Active ❌ Untick

Repository permissions:

Permission Access Why
Administration Read and write Create a repo for each new blog
Contents Read and write Push the built site
Pages Read and write Switch on Pages, set custom domains and HTTPS
Metadata Read-only Required by GitHub (selected automatically)

Leave every Account permission at No access.

Where can this GitHub App be installed? → Only on this account.

Click Create GitHub App. On the page that opens, copy the Client ID (it looks like Iv23li…). You don't need a client secret or a private key, so don't generate them.

2. Install it on your account

On the app's page, click Install App in the left sidebar, then Install next to your account. Choose All repositories, because folderblog creates new repositories for new blogs and the app needs access to them.

What this allows. With these settings, the login stored on your machine can create and delete repositories on your account. It is kept in ~/.config/folderblog/github.json, readable only by you, and expires unless folderblog renews it. Treat that file like an SSH key. You can revoke the login at any time (see below).

3. Log in

folderblog login github --client-id Iv23li...

folderblog shows a code. Open https://github.com/login/device, enter it, and approve. You only pass --client-id the first time; it is remembered.

Open https://github.com/login/device and enter the code:  4DC2-EA36
logged in to GitHub as yourname; this login lasts about 181 days and renews itself

4. Create blogs

folderblog new myblog                                  # → https://yourname.github.io/myblog/
folderblog new yourname.github.io                      # → https://yourname.github.io/ (your user site)
folderblog new example.com --domain example.com        # → https://example.com/
folderblog new notes --repo my-notes-site              # choose the repo name

new writes the GitHub details into the blog's blog.toml. On the first publish, folderblog creates the public repo (yourname/myblog), pushes the site to its gh-pages branch and makes sure Pages serves it. You can also create a blog by copying any blog folder into ~/Blogs and editing repo in its blog.toml. The service picks it up by itself.

Custom domains

  1. Create the blog with --domain (or add domain = "example.com" under [deploy] and set base_url = "https://example.com").
  2. Add DNS records at your domain registrar. folderblog new prints the exact records:
    • Subdomain (blog.example.com): a CNAME record pointing to yourname.github.io.
    • Apex domain (example.com): four A records: 185.199.108.153, 185.199.109.153, 185.199.110.153, 185.199.111.153 (and optionally a CNAME for www → yourname.github.io).
  3. Wait for DNS to spread (minutes to hours). folderblog sets the domain on Pages, keeps the CNAME file in place on every publish, and switches on "Enforce HTTPS" as soon as GitHub has issued the certificate.

Recommended: verify your domain in GitHub's settings so nobody else can claim it. That step is done on github.com.

Login expiry and revoking

  • Access renews itself automatically. You only log in again about every 6 months, and folderblog warns you a week before.
  • If the login expires or is revoked, you get one desktop notification (then a daily reminder), folderblog status says so, and publishing pauses. Your posts keep building locally, and everything waiting publishes within 5 minutes of folderblog login github.
  • To revoke: GitHub → Settings → Applications → Authorized GitHub Apps → Revoke. To forget the login locally: folderblog logout github.

Private repositories

Add private = true under [deploy] before the first publish. GitHub Pages on private repos needs a paid GitHub plan.

Running in the background

folderblog install-service      # enables the systemd user service and starts it now
folderblog status               # every blog: last build, last publish, GitHub Pages build, login
journalctl --user -u folderblog -f

If you installed a package, this is the same as systemctl --user enable --now folderblog. The service watches ~/Blogs. For a different folder, run systemctl --user edit folderblog and add Environment=FOLDERBLOG_ROOT=/path/to/blogs under [Service].

No systemd user session (a container, a headless server, a plain SSH login): install-service fails with systemctl --user daemon-reload failed. Either run folderblog watch in a terminal or tmux (same loop, in the foreground), or run loginctl enable-linger $USER, log in again and retry.

When the service starts it builds every blog once, so changes made while it was stopped are published. Failed publishes (offline, login expired…) are retried every 5 minutes.

After updating folderblog, restart the service (systemctl --user restart folderblog). On its first start with a new version it brings each blog up to date: it adds sample files the blog doesn't have yet (like templates/) and refreshes the generated part of AGENTS.md, writes dates.toml if the blog doesn't have one yet, and logs what it changed. It never turns a feature on and never changes theme/, blog.toml or your posts. A sample file you delete is not put back.

folderblog status exits with code 1 when anything is failing, so it also works in scripts and status bars.

Writing

~/Blogs/myblog/
  blog.toml     title, address, post URL pattern, where to publish, your own settings
  posts/        Markdown files, or a folder per post with its images beside it
  pages/        about.md -> /about/ ; an .html file here is rendered as its own design
  drafts/       only shown in `folderblog preview`
  static/       copied to the site root untouched (favicon, CNAME, downloads)
  data/         JSON/TOML/YAML files available to templates
  gallery/      pictures for the photo gallery (after `folderblog gallery on`)
  podcast/      the show and one folder per episode (after `folderblog podcast on`)
  theme/        all templates and styles; this decides what the site looks like
  templates/    a sample post and podcast episode with every front matter field, to copy
  AGENTS.md     the theme contract for coding agents (generated)
  dates.toml    when folderblog first saw each undated post (written for you; keep it)
  .blog/        folderblog's own state; ignore it

A post can be just text:

# Why I keep a paper notebook

Every few years I try to go fully digital…
  • Title: front matter title, else the first heading (removed from the body so it isn't shown twice), else the filename.
  • Address: from the filename. why-notebooks.md becomes /2026/09/why-notebooks/ by default (change permalink in blog.toml).
  • Date: front matter date, else a filename prefix like 2026-09-30-, else when folderblog first saw the file. That date is recorded in dates.toml in the blog folder and never moves, even if you edit the post or your sync tool touches it. Keep dates.toml with the blog (it isn't ignored by git) so a clone or copy gives undated posts the same addresses.
  • Time of day: every listing (home page, archives, tag pages, feeds, sitemap) is newest first by date and time. To set the time yourself, write it in date: date: 2026-11-10T09:28:00-06:00, or date: 2026-11-10 09:28 for the site's time zone (timezone in blog.toml, default: your computer's). A post whose date has no time (a filename date, or date: 2026-11-10) gets one so same-day posts keep a stable order: the time the file was first committed to git, else the file's modification time. That time is recorded in dates.toml the first time folderblog publishes the post, so later edits never reshuffle the day. Only the time comes from there: the day, and so the address, still comes from the filename or date. Feeds carry the full time; theme pages show whatever their date(...) format asks for (the default theme shows the day).
  • Typos: an unreadable date is a warning when the filename has a date to fall back on (folderblog check lists it), and an error otherwise, since folderblog would otherwise record a permanent date (and address) made from the typo. An unreadable updated is a warning and is left out.
  • Excerpt: everything before a <!--more--> line, else the first paragraph.

Optional front matter (YAML between --- or TOML between +++):

---
title: A walk on the Ridgeway
date: 2026-03-21
updated: 2026-04-01    # also `modified` or `lastmod`
tags: [walking, photos]
summary: Chalk, larks and a long way round.   # or `excerpt`: your own preview text
slug: ridgeway         # the last part of the address
url: /walks/ridgeway/  # or the whole address
layout: photo          # use theme/_layouts/photo.html for this post
draft: true            # keep it out of the live site
image: track.jpg       # share image for link previews (a path beside the post, or a URL)
weight: 10             # pages only: smaller comes first in the menu
anything: you like     # passed through to templates as post.meta.anything
---

Templates to copy: templates/post.md in every blog has all of these with a note on each, and starts as a draft. Copy it into posts/, fill it in, delete the lines you don't need and the draft: true line. templates/podcast-episode/ is the same for an episode. Blogs made before 0.2.6 get the folder when the service restarts on 0.2.7 or later, or straight away with folderblog templates. The folder is never published.

Images: put a post in its own folder (posts/ridgeway/index.md) with its images beside it and write ![Chalk track](track.jpg). Loose files in posts/ or static/ work too.

Share images: image: becomes the post's og:image and twitter:image (as an absolute URL, with its width and height when it is a file in the blog). Posts without one use the site's default: static/og-default.png (1200×630 works well everywhere), or whatever blog.toml image names.

Unpublish: delete the file, or move it to drafts/.

If a file has a mistake folderblog can't safely guess around (broken front matter, an unreadable date), that blog's build stops, you get a notification, and the live site keeps the last good version until you fix it.

Photo gallery

folderblog gallery on          # in the blog folder, or: folderblog gallery on ~/Blogs/myblog

This sets [gallery] enabled = true in blog.toml, creates gallery/, and adds the gallery templates to theme/_gallery/ (it never overwrites ones you already have). Then:

gallery/
  index.md                optional: "# Photographs" and an intro paragraph
  harbour.jpg             a photo; no other file needed
  harbour.md              optional sidecar: title, caption, tags
  2024-06-01-picnic.jpg   a date prefix sets the photo's date
  iceland/                a folder is an album
    index.md              optional: album title, date, tags, cover, description
    IMG_2041.jpg

A sidecar is a normal Markdown file with the photo's name:

---
tags: [sea, mornings]
alt: Fishing boats in a flat calm harbour
---
# The harbour at dawn

Before the boats go out, the water is completely still.
  • Every photo gets its own page, every album and tag gets a page, and the gallery page shows albums, tags and a justified photo grid. Clicking a photo opens a full-screen viewer (arrow keys and swipe work); without JavaScript it opens the photo's page.
  • The date is the sidecar date, else a filename date, else when the camera took it, else when folderblog first saw the file. Camera settings (lens, aperture, shutter, ISO) are shown on the photo page.
  • Tags in an album's index.md apply to every photo in it. draft: true hides a photo.
  • Only resized copies are published (2048 px and a thumbnail), never your originals, so the GPS location your phone stores in each picture never reaches the site. Resizing happens once per photo and is cached, so later builds stay fast.
  • JPEG, PNG, WebP and GIF work. HEIC (iPhone) and RAW files are skipped with a warning; export them as JPEG.
  • The default theme links to the gallery from its navigation once it has photos. For another theme, add {% if gallery.enabled and gallery.count %}<a href="{{ gallery.url }}">{{ gallery.title }}</a>{% endif %} to theme/_layouts/base.html. The gallery pages use the theme's own layout, fonts and colours, and theme/_gallery/ is yours to restyle (AGENTS.md documents every field).

folderblog gallery off turns it off again and leaves your pictures where they are.

Podcast

A podcast is one more part of the blog, with its own folder:

folderblog podcast on          # in the blog folder, or: folderblog podcast on ~/Blogs/myblog

This sets [podcast] enabled = true and a permanent guid in blog.toml, creates podcast/, adds the templates to theme/_podcast/ (never overwriting yours), and adds the audio file types under podcast/ to .gitignore. Then:

podcast/
  index.md                       the show's title and description
  cover.jpg                      show art: square, 1400-3000 px, JPEG or PNG
  2026-10-30-first-episode/
    index.md                     show notes; front matter guid, season, episode, summary…
    episode.mp3                  MP3 for audio, MP4 for video
    transcript.vtt               optional (.vtt or .srt), published beside the episode
    chapters.json                optional Podcasting 2.0 chapters
  • The show page is /podcast/, each episode /podcast/<slug>/, and the feed /podcast/feed.xml (iTunes and Podcasting 2.0: podcast:guid, podcast:locked, transcripts, chapters, persons, funding, and podcast:value for a Lightning address).
  • Size, duration and type are read from the file (and cached in .blog/); you never write them by hand. Only MP3 and MP4 are accepted; anything else gets a clear message.
  • Audio is never copied into the built site. Enclosures point at [podcast.storage] public_url as <public_url>/<prefix>/<slug>-<hash>.mp3, so an edited file gets a new URL. prefix (under [podcast.storage]; podcast setup sets it) is the folder on the host; left out, it is the blog folder's name, so renaming the folder would change every episode URL. folderblog check suggests pinning it. Until that is set, episodes are left out of the build. folderblog preview plays the local file.
  • folderblog podcast setup connects Cloudflare R2 step by step, even for someone with no Cloudflare account yet: sign-up, turning on R2 (free up to 10 GB a month, but Cloudflare asks for a card), then either one pasted API token (folderblog makes the bucket and its r2.dev address or connects your domain) or a bucket and key you made yourself. It checks the bucket with a test upload, a HEAD, a public download and a delete before saving anything. The key goes to ~/.config/folderblog/storage/<bucket>.json (mode 0600), never into blog.toml or the blog folder. A custom domain is recommended; r2.dev is rate-limited and Cloudflare says it isn't for production, but it's fine to start with.
  • Any other S3-compatible host (Backblaze B2, Wasabi, MinIO, AWS S3…) works with type = "s3": set endpoint (the S3 API URL), bucket, public_url and, if the host needs it, region under [podcast.storage]. podcast setup only connects R2, so give the key yourself: either the environment variables FOLDERBLOG_STORAGE_KEY_ID and FOLDERBLOG_STORAGE_SECRET (handy in CI; for the background service, add them with systemctl --user edit folderblog), or a file ~/.config/folderblog/storage/<bucket>.json containing {"access_key_id": "…", "secret_access_key": "…"} (chmod 600 it). The variables win when both are there.
  • Deploys upload new episode files first (in parts above 100 MB; a manifest in .blog/ skips files already uploaded), then HEAD each one and compare its size. If anything fails, the whole deploy is held (and retried every 5 minutes if the service is running), so the feed never points at missing audio. Drafts are never uploaded.
  • Episodes stay on /podcast/ by default; in_main_feed = true (or in_main_feed: true on one episode) also lists them with the posts and in /feed.xml.
  • folderblog check is strict about podcasts: required tags, https everywhere, known length and duration, real MP3/MP4 data, art size, Apple categories, valid chapters and transcripts, and episode guids that are unique and unchanged since the last deploy.
  • folderblog podcast lists the episodes, the feed URL, whether an analytics prefix is on, and any problems.

Publishing an episode by hand:

  1. Copy templates/podcast-episode/ to podcast/2026-10-30-first-episode/ (the date prefix is the episode date) and put the MP3 or MP4 beside index.md.
  2. Fill in index.md: the title, summary, season and episode number, people, show notes. Every field is listed in the template with a note.
  3. Run folderblog check. It gives you a guid line to paste in (write it once, never change it; it suggests the same one every time) and names anything else that needs fixing. While the episode is still draft: true these show up as warnings. folderblog preview plays the episode locally.
  4. Remove draft: true, or run folderblog podcast publish --episode first-episode. That changes only the draft: line to draft: false (your notes and comments stay), uploads the audio, checks it is online, then publishes the site and feed.

To get the show into Apple Podcasts, Spotify and the others, submit the feed URL that folderblog podcast prints (https://<your site>/podcast/feed.xml) once.

folderblog podcast off turns it off again and leaves your episodes where they are.

Podcast stats with OP3

OP3 is a free, open-source podcast analytics prefix. Turn it on with one line (off by default; existing feeds don't change):

[podcast]
analytics_prefix = "https://op3.dev/e/"    # or op3 = true, the same thing

Every enclosure in /podcast/feed.xml (and in /feed.xml with in_main_feed) then goes through the prefix in the form OP3 documents on op3.dev/setup: the URL without https:// (an http:// URL would keep its scheme), with the show's podcast:guid passed as the optional pg argument, e.g. https://op3.dev/e,pg=<guid>/media.example.com/myblog/pilot-1a2b3c4d.mp3. Uploads, the deploy's HEAD size check and the episode page's <audio> player use the real URL; OP3 counts podcast-app downloads, and the page keeps working if the prefix is down. Themes that want the prefixed URL can use episode.audio.enclosure. Any other prefix service works the same way; the prefix must be https:// and end in /, a URL already behind it is never prefixed again, and a public_url that includes it is refused.

There is nothing to register: OP3 identifies the show from the downloads. After a few days, its public stats page is at https://op3.dev/show/<guid> (the guid in [podcast]); the form on op3.dev/setup looks a feed up.

Let an agent put up episodes (MCP)

folderblog mcp is an MCP server on stdio. Point an agent at an audio file and say "put this up": it inspects the file, creates a draft episode, writes the show notes, chapters and Podcasting 2.0 details, validates, and publishes only after you say yes. The server calls no AI itself, never returns secrets, and only writes inside <blog>/podcast/.

Tool What it does Writes?
podcast_status Show settings, hosting (key masked), episode counts, problems no
list_episodes Episodes with draft state, URL, guid, duration, check status no
inspect_audio Size, duration, format, bitrate, embedded title; MP3/MP4 only no
create_episode Copies the audio (and transcript) into podcast/<date>-<slug>/, writes index.md with draft: true and a new guid, numbers it draft only
update_episode Changes front matter or notes, adds a transcript; strict validation yes
set_chapters Writes a valid chapters.json yes
validate folderblog check plus the podcast rules, drafts included no
publish_episode Needs confirm: true (marked destructiveHint): sets draft: false (only that line of index.md changes), uploads, deploys, checks the hosted file, returns the episode and feed URLs yes, public

Every tool takes blog: a path, or a blog's name under ~/Blogs (--root or FOLDERBLOG_ROOT changes it). With [podcast] mcp_publish = false, publish_episode returns folderblog podcast publish --episode SLUG BLOG for you to run instead.

Claude Code:

claude mcp add folderblog -- folderblog mcp

Cursor (~/.cursor/mcp.json) and Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "folderblog": { "command": "folderblog", "args": ["mcp"] }
  }
}

Themes and design

Every new blog gets a plain, readable default theme in theme/. Change anything: it is all yours, and there is no hidden base theme.

The fastest way to redesign a blog is to point a coding agent at the blog folder:

Read AGENTS.md, then redesign this blog as a dense magazine layout with tag pages and search.

AGENTS.md documents everything an agent needs: how files in theme/ become pages, the full template context, filters, and the commands for checking its own work. The engine regenerates it (folderblog agents-md --write) and tests that it matches what the engine actually does.

Useful while designing:

folderblog preview                    # http://127.0.0.1:4000, live reload, drafts included
folderblog preview --fixtures stress  # your theme against long titles, code, tables, images, empty lists…
folderblog check                      # template errors with file:line, feed validation, broken links
folderblog check --fixtures empty
folderblog data                      # every URL and what made it
folderblog data /archive/             # the exact template context for one of them, as JSON

In short:

  • theme/**/*.html and *.jinja files are templates rendered to the same path, and everything else is copied. A template that starts with a route header (a {#--- … ---#} comment holding url = "…") is published at that URL instead: the default theme/archive.html begins with url = "/archive/", so it becomes /archive/, not /archive.html.
  • Paths starting with _ (_layouts/, _partials/) are never published.
  • A template can declare each = "tags" to make one page per tag (or per year, per series, per anything).
  • /feed.xml and /sitemap.xml belong to the engine. /robots.txt too, unless static/robots.txt (or a theme file) provides one. With a base_url path (/blog), robots.txt ends up at /blog/robots.txt, which crawlers ignore; add Sitemap: <base_url>/sitemap.xml to the host's own robots.txt instead (check says so).
  • Every file in posts/ and pages/ is published, used or not; check lists pictures there that no page shows, so a stray one doesn't stay online unnoticed.

Configuration (blog.toml)

title = "Field Notes"
base_url = "https://yourname.github.io/myblog"   # where the site lives (may include a path)
description = "Notes from the workbench"
author = "Your Name"
language = "en"
permalink = "/{year}/{month}/{slug}/"            # tokens: {year} {month} {day} {slug}
# timezone = "America/Chicago"                   # for dates written without an offset (default: this computer's)
# image = "/img/share.png"                       # default share image (default: static/og-default.png)

[feed]
limit = 20                                       # posts in /feed.xml (full content)

[deploy]
type = "github"
owner = "yourname"
repo = "myblog"
# branch = "gh-pages"
# domain = "example.com"
# private = false

# Optional build hooks (e.g. Tailwind). Hooks live here, never in the theme, so copying
# someone's theme into your blog can't run code.
[build]
pre = []
post = []                                        # $FOLDERBLOG_OUT is the fresh build folder

[watch]
ignore = []                                      # paths that never trigger a rebuild

[gallery]
enabled = false                                  # `folderblog gallery on` turns it on
url = "/gallery/"

[podcast]
enabled = false                                  # `folderblog podcast on` turns it on
category = "Technology"                          # an Apple Podcasts category
owner_email = "you@example.com"                  # public in the feed
# lightning_address = "you@rizful.com"           # optional podcast:value tips
# in_main_feed = false                           # also list episodes with posts
# analytics_prefix = "https://op3.dev/e/"       # download stats with OP3

[podcast.storage]
type = "r2"                                      # set by `folderblog podcast setup`
account_id = "..."
bucket = "myblog-podcast"
public_url = "https://media.example.com"         # where episode files are hosted
prefix = "myblog"                                # folder on the host for episode files

# Optional, off by default. See "Analytics" below.
# [analytics]
# goatcounter = "https://stats.example.com"

[params]                                         # anything you like, for templates
tagline = "Notes from the workbench"

The full, always-current reference is the blog.toml section of each blog's AGENTS.md.

Analytics (optional)

Off by default: without an [analytics] section the output is exactly what it always was. To count page views with GoatCounter, which is cookie-free and records no personal data, point it at your GoatCounter site, self-hosted or hosted:

[analytics]
goatcounter = "https://stats.example.com"   # base URL of your GoatCounter site (https:// only)
# host_prefix = true                        # default: count pages as "host/path"

build, deploy and watch then add GoatCounter's two <script> tags just before </head> of every rendered HTML page (posts, pages, home, archives, tags, gallery, 404), whatever the theme. host_prefix lets one GoatCounter site count several blogs and tell them apart; set it to false for plain paths. On the 404 page the hit is counted as a GoatCounter event named 404 host/path (or 404 /path), so broken links show up apart from real page views. preview and build --drafts / --fixtures never add it, files in static/ are copied untouched, and a page that already includes data-goatcounter is left alone. If your theme sets a Content-Security-Policy, allow the GoatCounter host for scripts and images.

Other hosts

First set base_url at the top of blog.toml to the address where the site will live (folderblog new --no-github, or new while logged out, leaves the placeholder https://NAME.example.com, and every absolute link, the feeds and the sitemap are made from it; folderblog check warns while it's still the placeholder).

Any git remote / branch (uses your normal git credentials):

[deploy]
type = "git"
remote = "git@github.com:you/site.git"
branch = "gh-pages"

Anything else: rsync, rclone, Cloudflare (wrangler), Netlify CLI, S3… The command runs in the blog folder with $FOLDERBLOG_OUT pointing at the finished site:

[deploy]
type = "command"
command = 'rsync -a --delete "$FOLDERBLOG_OUT/" me@server:/var/www/blog/'
# command = 'npx wrangler pages deploy "$FOLDERBLOG_OUT" --project-name blog'

folderblog only publishes when the built site actually changed.

Blog folder kept in git? Add deploy_branch = "main" at the top of blog.toml. Deploys then only happen while the folder is on that branch with no merge, rebase, cherry-pick or revert in progress, so switching branches or rebasing in the live folder can't publish unreviewed posts. A held deploy counts as a failed one: you get a notification, folderblog status shows the held: … reason, and the watcher's retry publishes once you're back on the branch. Uncommitted edits on the branch still publish.

Commands

Command What it does
folderblog new NAME [--domain D] [--repo R] [--no-github] Create a blog in ~/Blogs/NAME (published to GitHub Pages if logged in)
folderblog login github [--client-id ID] Connect your GitHub App (once)
folderblog logout github Forget the GitHub login
folderblog install-service Run watch in the background (systemd user service)
folderblog status [--json] Build/publish state of every blog, GitHub login and Pages builds
folderblog watch The background process itself: watch, build, publish
folderblog deploy [BLOG] [--force] Build and publish one blog now
folderblog build [BLOG] [--out DIR] [--drafts] Build without publishing
folderblog preview [BLOG] [--port N] [--fixtures SET] Local preview with live reload
folderblog check [BLOG] [--fixtures SET] Find template errors, feed problems, broken links
folderblog data [URL] Template context for a page (or list all pages)
folderblog gallery [on|off] [BLOG] Turn the photo gallery on or off (adds gallery/ and its templates)
folderblog podcast [on|off|setup|publish] [BLOG] Turn the podcast on or off, set up audio hosting on Cloudflare R2, publish an episode (--episode SLUG), or list episodes and problems
folderblog mcp [--root DIR] MCP server on stdio for agents: draft, check and (after your yes) publish episodes
folderblog agents-md [BLOG] [--write] Refresh the blog's AGENTS.md
folderblog templates [BLOG] Add the sample post and episode to templates/ (only missing files)
folderblog guide The step-by-step guide to everything (docs/GUIDE.md)
folderblog man The same guide as a manual page (man folderblog once installed)

BLOG defaults to the current folder. FOLDERBLOG_ROOT or --root changes ~/Blogs.

Troubleshooting

Nothing happens when I save. Run folderblog status. If the service is shown as inactive, run folderblog install-service. Check the log with journalctl --user -u folderblog -f.

"not logged in to GitHub" / "GitHub login expired". Run folderblog login github. Pending posts publish within 5 minutes.

"GitHub refused to start a login". Check the Client ID, and that Enable Device Flow is ticked in the app's settings.

Creating the repo fails with 403 / "Resource not accessible by integration". The app is missing a permission or isn't installed. Recheck step 1 (Administration, Contents, Pages = Read and write) and step 2 (installed on All repositories). After changing an app's permissions, GitHub asks you to approve the change on the installation page.

The site shows GitHub's 404 for a few minutes after the first publish. That's GitHub's first Pages build. folderblog status shows its progress (pages … building → built).

Links or styles break on yourname.github.io/myblog/. base_url must include the /myblog part. folderblog new sets this for you. Themes should use the URLs folderblog provides, or the | url filter, rather than hard-coded /… paths.

No desktop notifications. Install libnotify (notify-send). Under the systemd service the notification needs your desktop session's environment. Most desktops export it; if not, add systemctl --user import-environment DISPLAY WAYLAND_DISPLAY DBUS_SESSION_BUS_ADDRESS to your session startup.

A template error. folderblog check names the file and line. The live site keeps its last good version until it's fixed.

An episode doesn't show up. Run folderblog podcast. Episodes stay out of the build while they are drafts, while audio hosting isn't set up (folderblog podcast setup), or while they have a problem, which it lists. A failed audio upload holds the whole publish and is retried every 5 minutes.

My blog has no templates/ folder after updating. The service adds it when it restarts on the new version: systemctl --user restart folderblog. Or run folderblog templates ~/Blogs/myblog.

How it stays safe

  • It never modifies your posts or pages, so editors with the file open never complain. On its own it writes only its own files: .blog/, dates.toml, the generated part of AGENTS.md and missing samples in templates/. Commands you run on purpose (gallery on, podcast on, podcast setup) also change blog.toml and add their folders and theme templates, never overwriting yours. Episode files change only through folderblog podcast publish and the MCP tools, which write nothing outside podcast/.
  • Each build goes into a fresh folder and swaps in only if every page rendered. A failed build leaves the live site exactly as it was.
  • Editors that save by writing a temp file and renaming it are handled. Swap files, backups and sync-tool debris are ignored, and bursts of saves become one build.
  • Blogs build independently, so a broken blog never blocks another.
  • The GitHub login is stored only on your machine (~/.config/folderblog/github.json, mode 600). It is sent to GitHub per request and never written into git config.
  • Build hooks can only come from your blog.toml, never from a theme.
  • Storage keys for podcast audio live in ~/.config/folderblog/storage/ (mode 600). They are never written into the blog, blog.toml, logs or MCP replies, and never passed as command-line arguments.
  • The service and a podcast publish (from the CLI or an agent) take turns through a lock, so two builds or deploys of the same blog never run at once.

Building from source

git clone https://github.com/ninepointlabs/folderblog && cd folderblog
cargo build --release              # target/release/folderblog
cargo test                         # engine tests, including the AGENTS.md contract
tests/e2e.sh                       # watch + two blogs + local git remotes + failure/recovery

Release packages (static musl binary, .deb, .rpm, Arch package, SHA256SUMS):

rustup target add x86_64-unknown-linux-musl
cargo install cargo-deb cargo-generate-rpm
packaging/build-release.sh          # needs clang; makepkg for the Arch package

To add a new publishing target, implement deploy::Target in src/deploy.rs and add a variant to DeployConfig in src/config.rs.

License

MIT. See LICENSE.

About

A folder is a blog: save Markdown into a folder and it's published to GitHub Pages (or anywhere) seconds later. Themes designed by coding agents.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages