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, orman 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
- Install
- Quick start
- Preparing GitHub (one time, about 5 minutes)
- Running in the background
- Writing
- Photo gallery
- Podcast (and MCP for agents)
- Themes and design
- Configuration (
blog.toml) - Other hosts
- Commands
- Troubleshooting
- How it stays safe
- Building from source
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 indates.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.mdand its images inposts/my-trip/and relative image paths just work. - Pages (
pages/about.md→/about/), drafts that only appear in preview, astatic/folder copied as-is, anddata/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.mdbeside 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, whichfolderblog podcast setupconnects 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 refreshesAGENTS.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.txtthat 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). previewwith 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.
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.zstDebian / 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.debFedora / RHEL / openSUSE
sudo dnf install https://github.com/ninepointlabs/folderblog/releases/download/v0.2.11/folderblog-0.2.11-1.x86_64.rpmAny 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/folderblogWith 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.
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:4000To 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.mdAbout 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.
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.
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.
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).
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
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 namenew 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.
- Create the blog with
--domain(or adddomain = "example.com"under[deploy]and setbase_url = "https://example.com"). - Add DNS records at your domain registrar.
folderblog newprints the exact records:- Subdomain (
blog.example.com): aCNAMErecord pointing toyourname.github.io. - Apex domain (
example.com): fourArecords:185.199.108.153,185.199.109.153,185.199.110.153,185.199.111.153(and optionally aCNAMEforwww→yourname.github.io).
- Subdomain (
- Wait for DNS to spread (minutes to hours). folderblog sets the domain on Pages, keeps
the
CNAMEfile 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.
- 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 statussays so, and publishing pauses. Your posts keep building locally, and everything waiting publishes within 5 minutes offolderblog login github. - To revoke: GitHub → Settings → Applications → Authorized GitHub Apps → Revoke. To forget
the login locally:
folderblog logout github.
Add private = true under [deploy] before the first publish. GitHub Pages on private
repos needs a paid GitHub plan.
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 -fIf 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.
~/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.mdbecomes/2026/09/why-notebooks/by default (changepermalinkinblog.toml). - Date: front matter
date, else a filename prefix like2026-09-30-, else when folderblog first saw the file. That date is recorded indates.tomlin the blog folder and never moves, even if you edit the post or your sync tool touches it. Keepdates.tomlwith 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, ordate: 2026-11-10 09:28for the site's time zone (timezoneinblog.toml, default: your computer's). A post whose date has no time (a filename date, ordate: 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 indates.tomlthe 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 ordate. Feeds carry the full time; theme pages show whatever theirdate(...)format asks for (the default theme shows the day). - Typos: an unreadable
dateis a warning when the filename has a date to fall back on (folderblog checklists it), and an error otherwise, since folderblog would otherwise record a permanent date (and address) made from the typo. An unreadableupdatedis 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 . 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.
folderblog gallery on # in the blog folder, or: folderblog gallery on ~/Blogs/myblogThis 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.mdapply to every photo in it.draft: truehides 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 %}totheme/_layouts/base.html. The gallery pages use the theme's own layout, fonts and colours, andtheme/_gallery/is yours to restyle (AGENTS.md documents every field).
folderblog gallery off turns it off again and leaves your pictures where they are.
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/myblogThis 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, andpodcast:valuefor 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_urlas<public_url>/<prefix>/<slug>-<hash>.mp3, so an edited file gets a new URL.prefix(under[podcast.storage];podcast setupsets 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 checksuggests pinning it. Until that is set, episodes are left out of the build.folderblog previewplays the local file. folderblog podcast setupconnects 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": setendpoint(the S3 API URL),bucket,public_urland, if the host needs it,regionunder[podcast.storage].podcast setuponly connects R2, so give the key yourself: either the environment variablesFOLDERBLOG_STORAGE_KEY_IDandFOLDERBLOG_STORAGE_SECRET(handy in CI; for the background service, add them withsystemctl --user edit folderblog), or a file~/.config/folderblog/storage/<bucket>.jsoncontaining{"access_key_id": "…", "secret_access_key": "…"}(chmod 600it). 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(orin_main_feed: trueon one episode) also lists them with the posts and in/feed.xml. folderblog checkis 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 podcastlists the episodes, the feed URL, whether an analytics prefix is on, and any problems.
Publishing an episode by hand:
- Copy
templates/podcast-episode/topodcast/2026-10-30-first-episode/(the date prefix is the episode date) and put the MP3 or MP4 besideindex.md. - Fill in
index.md: the title, summary, season and episode number, people, show notes. Every field is listed in the template with a note. - Run
folderblog check. It gives you aguidline 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 stilldraft: truethese show up as warnings.folderblog previewplays the episode locally. - Remove
draft: true, or runfolderblog podcast publish --episode first-episode. That changes only thedraft:line todraft: 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.
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 thingEvery 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.
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 mcpCursor (~/.cursor/mcp.json) and Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"folderblog": { "command": "folderblog", "args": ["mcp"] }
}
}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 JSONIn short:
theme/**/*.htmland*.jinjafiles are templates rendered to the same path, and everything else is copied. A template that starts with a route header (a{#--- … ---#}comment holdingurl = "…") is published at that URL instead: the defaulttheme/archive.htmlbegins withurl = "/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.xmland/sitemap.xmlbelong to the engine./robots.txttoo, unlessstatic/robots.txt(or a theme file) provides one. With abase_urlpath (/blog), robots.txt ends up at/blog/robots.txt, which crawlers ignore; addSitemap: <base_url>/sitemap.xmlto the host's own robots.txt instead (checksays so).- Every file in
posts/andpages/is published, used or not;checklists pictures there that no page shows, so a stray one doesn't stay online unnoticed.
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.
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.
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.
| 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.
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.
- 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 ofAGENTS.mdand missing samples intemplates/. Commands you run on purpose (gallery on,podcast on,podcast setup) also changeblog.tomland add their folders and theme templates, never overwriting yours. Episode files change only throughfolderblog podcast publishand the MCP tools, which write nothing outsidepodcast/. - 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.
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/recoveryRelease 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 packageTo add a new publishing target, implement deploy::Target in src/deploy.rs and add a
variant to DeployConfig in src/config.rs.
MIT. See LICENSE.