folderblog 0.2.3: Better link previews, optional visitor counts, and safer deploys

folderblog turns a folder of Markdown into a live blog the moment you save. Two releases since the last word here, 0.2.2 and 0.2.3, make what it publishes look better when it’s shared and searched, add an opt-in visitor counter, and stop a blog kept in git from deploying half-finished work.

Share images for every post

Add image: to a post’s front matter, either a path inside the blog or a full URL, and it becomes that post’s og:image and twitter:image. folderblog writes it as an absolute URL and adds the width and height when the file lives in the blog. Posts without one fall back to static/og-default.png, or to a new optional image key in blog.toml.

---
title: "My post"
image: img/cover.jpg
---

folderblog check warns when the image doesn’t exist, so a typo doesn’t quietly ship a broken preview card.

Search engines get the whole picture

The default theme now gives every page a meta description, a canonical link, the full set of OpenGraph tags, and a twitter:card. Post pages carry BlogPosting structured data (JSON-LD), and the home page has a single h1 with the site title.

folderblog also writes a robots.txt by default that allows everything and points to the sitemap. If your blog has its own static/robots.txt, or your theme provides one, yours wins. And check now warns when blog.toml has no description.

If you keep your own copy of the theme in theme/, your templates are left alone. Copy the new default theme’s _layouts/base.html and post.html to pick up the tags, and run folderblog agents-md --write in each blog folder to refresh its AGENTS.md.

Optional visitor counts with GoatCounter

Want to know whether anyone reads the thing? Add one section to blog.toml:

[analytics]
goatcounter = "https://you.goatcounter.com"

Every rendered page gets GoatCounter’s cookie-free counting script, with any theme and no template edits. It’s off by default: with no [analytics] section the output is byte-for-byte what it was before. It’s never added by preview or build --drafts, so your own drafting doesn’t count as visits, and check flags an invalid URL.

Hold deploys while you’re mid-git

0.2.2 added deploy_branch for blog folders you keep in git:

deploy_branch = "main"

With it set, folderblog only deploys while the folder is a checkout of that branch. On another branch, a detached HEAD, or in the middle of a merge, rebase or cherry-pick, the deploy is held and shows as held: ... in folderblog status. It retries on its own once you’re back on the branch. Leave it unset and nothing changes. This blog runs with it on.

One note for both releases: older versions reject unknown keys in blog.toml, so upgrade before adding image, [analytics] or deploy_branch.

Grab it

The packages and a plain tarball are on the v0.2.3 release. New to folderblog? Start with the guide, or run folderblog guide.

Originally posted on blog.ninepointlabs.com.