Fabio Manganiello

Last Notes

2026-10-03 08:41:08 UTC

**[Songhive — A fully self-hosted and federated music platform](https://blog.fabiomanganiello.com/article/Songhive )**
**What if your music server had a social network attached, and your social network could play music?**
##
The problem
If you've ever tried to self-host your music, you've probably noticed that every tool solves exactly one half of the problem.
**Media servers** ([Jellyfin](https://jellyfin.org ), [Navidrome](https://navidrome.org ), plain [Subsonic](https://subsonic.org )) are great at the library half: point them at your FLAC collection, get streaming, transcoding, mobile apps. But they're single-player islands. Nobody else can discover your music, there's no social layer, and sharing a track means copy-pasting a file or a link that probably doesn't resolve outside your LAN, or creating accounts on your server for every person you want to share content with.
**Social music platforms** ([Funkwhale](https://www.funkwhale.audio ) being the closest thing) add the federation half, but the social experience is mostly library-oriented: you follow someone's *library* and sync their files. It's a distribution network, not a place where people talk about music. Moreover, most of those open platforms were never thought with revenue models in mind. Payments were never integrated. They're mostly places for artists to freely share their creations, not for them to monetize them.
**Streaming services** ([Spotify](https://spotify.com ), [Apple Music](https://apple.com/music ), [TIDAL](https://tidal.com )) are widespread, but they usually don't come with true built-in social features besides following someone else's playlists, or the "Share to Facebook/Instagram/TikTok" button. And consumers don't own anything: the catalog can shrink overnight, and shared URLs can often be viewed only by people who already have an account on the platform. Music creators don't have much of a say either. They get fractions of a cent, they don't fully control distribution (and often they need an intermediary just to distribute their music, which takes a share of the revenue too), and they often have to release to multiple music platforms just because those platforms don't talk with one another. Most importantly, your listening history is the product.
[**Bandcamp**](https://bandcamp.com ) tries to fix some of the issues, namely by putting content creators at the center and letting them own their own sales and monetization process (including sales of things like vinyls, CDs and merchandise). But it's still a centralized service whose [ownership changed hands](https://www.nytimes.com/2022/03/02/arts/music/epic-games-bandcamp.html ) [several times](https://www.bbc.com/news/technology-66953910 ). Users and artists are just one round of layoffs away from seeing the platform they invested in rot and/or enshittify, with no direct compatible alternatives. The social media aspect is also not something Bandcamp particularly invested in as well. The focus has increasingly shifted to sales, social interactions are basically limited to a "community" tab on artist pages, where artists can post updates and people can reply to. Any social interactions stay strictly confined to a tab on a centralized platform.
Perhaps the [old incarnation of **Google Music**](https://en.wikipedia.org/wiki/Google_Play_Music ) helped filled an important gap on user-generated content (it allowed users to upload up to 50,000 tracks to the cloud for free, making music collection sitting on old hard drives available on-the-go), but it didn't last long, and it didn't cover any social media and sharing needs.
And **MySpace** — the thing everyone actually remembers fondly — was never really any of these. It was a place where a band had a page, you could play their song right there, leave a comment, and add them as a friend. Nobody has successfully rebuilt that.
Songhive is an attempt to meet all these needs in one package: a self-hosted music streaming server where tracks, albums, playlists and posts are first-class [**ActivityPub**](https://activitypub.rocks/ ) objects. Think *Funkwhale meets Mastodon* — your music library lives on your hardware, or in any cloud storage you want to plug to it, but your music (and your posts about music) can travel across the fediverse, be followed from Mastodon, replied to, boosted, and quoted.
[[Screenshot of an instance's home page on desktop](https://s3.fabiomanganiello.com/fabio/screenshots/songhive/home-full.png )]
[[Screenshot of an instance's home page on mobile](https://s3.fabiomanganiello.com/fabio/screenshots/songhive/home-federated.png )]
[[Screenshot of a Subsonic app (Substreamer on Android) connected to a Songhive server](https://s3.fabiomanganiello.com/fabio/screenshots/songhive/subsonic-android.png )]
##
Who is this for
<li>Artists: publish tracks with a "Publish on the Fediverse" checkbox and they appear as playable <code>Audio</code> objects in Mastodon timelines. People can reply, boost and quote them from their existing fediverse account — no new signup required on your side. Your artist page, releases and playlists all expose RSS/Atom feeds, and blogs that support Webmentions will send you a notification when they link to your song. Native integration with Stripe also makes it easier for you to connect a payout account and put some of your tracks or albums for sale. You can choose how much of a paid song you want to share for streaming (only a sample, the full song or nothing), and how much users should pay for it. No shares of your revenue are taken besides the share taken by Stripe to process the transaction.</li>
<li>Bands who need an easy and flexible way to share their recordings, rehearsals, playlists of covers etc. Those who have played in a band know this issue quite well. Spotify playlists for covers to play are only good as long as everyone in the band has a premium Spotify account. YouTube playlists often result in precious rehearsal time wasted waiting for ads to end. Not to mention those <code>rehearsal.mp3</code> files shared between WhatsApp chats, emails and Dropbox or Google Drive folders, with no easy way of bringing them all together under the same roof - especially when you're looking for those recordings during a rehearsal. Songhive makes it easier to share whole tracks, albums or playlists with full control over the level of visibility. It makes it easier to integrate 3rd-party music streaming services so you can sync your playlist of covers and easily share it from a proxy platform without everyone having to have a Spotify or TIDAL premium account. It makes it easy to just plug that Google Drive folder where you carelessly dropped all the recordings of your band's rehearsal and sort them, tag them and share them as consistent collections with a single URL.</li>
<li>Self-hosters / library curators: point Songhive at your local folders, an S3 bucket, a WebDAV/SFTP share, Dropbox, Google Drive — or even import your collections from Jellyfin or TIDAL — and get a full streaming stack with transcoding, Subsonic mobile apps, Last.fm scrobbling, listening stats and automatic MusicBrainz/cover-art enrichment. Fine-grained visibility (<code>private</code> / <code>local</code> / <code>public</code>) means your 4,000-track hoard stays private while the three songs you actually wrote are public. Not only, but Songhive also taps into an issue that open projects like these often fail to address: how to provide incentives to sysadmins and self-hosters to run their servers. Especially when it comes to things like a music streaming server which, in terms of CPU, storage and bandwidth usage, is not free - and often not even cheap. Songhive provides the option for sysadmins to have a Paid registration mode. The admin can decide how much they want to charge users to use their instance and upload music to it, and how often they want to charge them. Subscriptions are handled transparently by Stripe and can be cancelled at any time. And admins can also set user quotas to keep things sane and prevent abuse.</li>
<li>People who want a MySpace-style music social network: run an instance for your scene, your label, your collective. Users get profiles, statuses with mentions and hashtags, threaded replies, quotes, notifications, and moderation tools (mute/block, reports, instance-level defederation). Your instance federates with Mastodon, so it's not a walled garden unless you want it to be.</li>
<li>Musicians with a multi-room house or a community radio streak: server-side outputs let playback keep running on the server after you close the tab — cast to Snapcast multi-room speakers, relay to an Icecast station, or host your own HTTP radio mountpoint with fan-out to unlimited listeners.</li>
##
What you get
###
The streaming stack
The core is a serious music library and streaming server:
<li>Library management with artists, albums, tracks, playlists and dynamic radio stations. Uploads get automatic tag extraction, duplicate detection, and metadata enrichment from MusicBrainz and the Cover Art Archive — including cover art and artist images fetched for you.</li>
<li>Streaming with on-the-fly transcoding (MP3, OGG, FLAC, AAC, Opus), HTTP range requests, and a transcode cache, with per-user/per-role bitrate caps (handy if your uplink or mobile data is precious).</li>
<li>Subsonic API compatibility, enabled by default. This is the sleeper feature: every Subsonic-compatible mobile/desktop client — Substreamer, Symfonium, Ultrasonic, Supersonic, Tempus and friends — works against your instance out of the box. You get a decade's worth of mature third-party players for free, and API tokens keep your real password out of them.</li>
<li>Mopidy integration via the <a href="https://github.com/blacklight/mopidy-songhive"><code>mopidy-songhive</code> extension</a> if that's your jam. - Listening history, favorites and scrobbling to Last.fm and Libre.fm out of the box, plus a personal listening-stats dashboard (top artists, calendar and hour-of-day heatmaps, release-year breakdowns) rendered with ECharts.</li>
[[A screenshot of the listening stats page, showing top listened artists and albums over a given time period](https://s3.fabiomanganiello.com/fabio/screenshots/songhive/listening-stats-1.png )]
[[A screenshot of the listening stats page, showing listened tracks grouped by release years and listening hours](https://s3.fabiomanganiello.com/fabio/screenshots/songhive/listening-stats-2.png )]
<li>Bulk downloads: select tracks/collections and get an async-built ZIP archive.</li>
<li>Server-side outputs — Spotify-Connect-style. The browser is just a remote control; audio is rendered by the server via a dedicated stream worker. Three providers: an Icecast relay (with live ICY metadata updates), a Snapcast provider for whole-home audio, and native HTTP mountpoints (<code>/streams/<mount></code>) served directly by Songhive with per-listener cursors over Redis Streams — no external radio server required. Playback keeps playing after you close the tab, and multiple tabs/devices stay in sync.</li>
<li>Payments support out of the box — set up a Stripe account and connect it to the instance, and configure it as a marketplace account if you also want to allow musicians to wire their payout accounts and sell music through your platform.</li>
[[A screenshot of a track uploaded by a musician, showing the options to set up payments for it](https://s3.fabiomanganiello.com/fabio/screenshots/songhive/artist-payment-form.png )]
[[A screenshot of the membership page on an instance with paid subscriptions](https://s3.fabiomanganiello.com/fabio/screenshots/songhive/membership-form.png )]
###
The social layer
This is where Songhive diverges from every other self-hosted media server. Federation is full ActivityPub (via the [pubby](https://github.com/blacklight/pubby ) library), and music entities are social objects:
<li>Every user is an ActivityPub actor, reachable at <code>@user@instance</code> via WebFinger, with Mastodon-style alias URLs. Mastodon users can follow, mention and interact with you from their own client.</li>
<li>Tracks are <code>Audio</code> objects. Publishing is explicit and opt-in per upload — your private library never leaks to the Fediverse by accident. Published tracks render as playable audio in Mastodon and Akkoma timelines, with descriptions, hashtags and link-backs to the track page.</li>
<li>Mastodon-style statuses with Markdown, mentions, hashtags, threaded replies, quotes and link preview cards. Reply to a track, boost an album drop, quote-post a playlist, or simply post some words to Mastodon and use it like a normal Mastodon account.</li>
<li>Funkwhale-compatible music federation: full bidirectional music federation with Funkwhale and other Songhive instances — remote libraries, albums, artists and tracks resolve as browsable resources you can follow and add to your collection.</li>
<li>Remote discovery: paste a Fediverse handle or URL into the search box and it's dereferenced, cached and browsable — SSRF-guarded and domain-moderated.</li>
<li>Real notifications over WebSocket (in-app, real-time), with per-type email and daily-digest preferences, plus optional OS-native push via VAPID WebPush.</li>
<li>Mastodon-grade moderation: users mute/block local and remote actors; admins limit/suspend actors, defederate or restrict instances, and review reports — optionally forwarding them to the reported actor's home instance via ActivityPub <code>Flag</code>.</li>
<li>RSS/Atom everywhere: every profile, artist, playlist, library, tag and genre has RSS 2.0 and Atom feeds with <code><link rel="alternate"></code> discovery, so even non-fediverse readers can subscribe.</li>
[[A Songhive post with a published song viewed from Mastodon](https://s3.fabiomanganiello.com/fabio/screenshots/songhive/mastodon-integration.png )]
###
Sharing and privacy
<li>Three-level visibility on tracks, albums, playlists and libraries: <code>private</code>, <code>local</code> (instance-only), or <code>public</code>.</li>
<li>Share grants (give a specific user access) and revocable share links — a short URL that renders a preview page with an audio player for anyone, content-negotiated so API clients get JSON and crawlers get OpenGraph metadata.</li>
<li>Embeddables: public tracks and collections embed on any web page via <code><audio></code> tags, Markdown links, a <code><script></code> widget or a no-JS iframe. Media endpoints send <code>Access-Control-Allow-Origin</code>, so fediverse clients can embed your audio too.</li>
<li>Webmentions: bidirectional link-backs for public content. A blog that links to your song sends you a notification; content you share or comment on sends a Webmention back to the source. All outbound/inbound fetches on this path are SSRF-guarded.</li>
[[Screenshot of the "Share Track" modal](https://s3.fabiomanganiello.com/fabio/screenshots/songhive/track-share.png )]
###
The platform bits
<li>Multi-user with open, invite-only, approval-required or closed registration; per-user profile visibility.</li>
<li>OAuth2 provider for third-party apps, plus API tokens for scripts and Subsonic clients.</li>
<li>Flexible storage: local filesystem, S3-compatible object storage.</li>
<li>External libraries — the feature that sells it to people with existing collections. Attach external music storage to a Songhive library: local folders (with a filesystem watchdog that picks up changes automatically), S3, SFTP, WebDAV, Dropbox, Google Drive, or plain HTTP. Entity-backed providers go further: Jellyfin and TIDAL import tracks, albums, artists and playlists as first-class library entries with lazily-fetched contents — audio bytes stay remote and are proxied at play time, so provider credentials never reach the client. Metadata can be written back to the provider, and Dropbox/TIDAL connect via OAuth straight from the settings form.</li>
<li>Metadata write-back: enriched tags are written into the audio files themselves, using audio-only content hashing — so re-tagging or swapping cover art never changes the stored path or invalidates the content hash. Since it support metadata write-back to the original file, you can also wire your existing music library on an old hard drive and use Songhive to fix broken audio metadata tags.</li>
##
How it compares
<thead>
<tr>
<th></th>
<th style="text-align: center;">Songhive</th>
<th style="text-align: center;">Funkwhale</th>
<th style="text-align: center;">Jellyfin/Navidrome</th>
<th style="text-align: center;">Mastodon</th>
<th style="text-align: center;">Spotify</th>
<th style="text-align: center;">Bandcamp</th>
</tr>
</thead>
<tbody>
<tr>
<td>Self-hosted</td>
<td style="text-align: center;">✅</td>
<td style="text-align: center;">✅</td>
<td style="text-align: center;">✅</td>
<td style="text-align: center;">✅</td>
<td style="text-align: center;">❌</td>
<td style="text-align: center;">❌</td>
</tr>
<tr>
<td>Streaming + transcoding</td>
<td style="text-align: center;">✅</td>
<td style="text-align: center;">✅</td>
<td style="text-align: center;">✅</td>
<td style="text-align: center;">❌</td>
<td style="text-align: center;">✅</td>
<td style="text-align: center;">✅</td>
</tr>
<tr>
<td>Subsonic API (mobile apps)</td>
<td style="text-align: center;">✅</td>
<td style="text-align: center;">✅</td>
<td style="text-align: center;">✅</td>
<td style="text-align: center;">❌</td>
<td style="text-align: center;">❌</td>
<td style="text-align: center;">❌</td>
</tr>
<tr>
<td>Scrobbling + listening stats</td>
<td style="text-align: center;">✅</td>
<td style="text-align: center;">partial</td>
<td style="text-align: center;">partial</td>
<td style="text-align: center;">❌</td>
<td style="text-align: center;">✅</td>
<td style="text-align: center;">❌</td>
</tr>
<tr>
<td>ActivityPub social (posts, replies, boosts)</td>
<td style="text-align: center;">✅</td>
<td style="text-align: center;">❌</td>
<td style="text-align: center;">❌</td>
<td style="text-align: center;">✅</td>
<td style="text-align: center;">❌</td>
<td style="text-align: center;">❌</td>
</tr>
<tr>
<td>Federated music objects playable in Mastodon</td>
<td style="text-align: center;">✅</td>
<td style="text-align: center;">partial (library-oriented)</td>
<td style="text-align: center;">❌</td>
<td style="text-align: center;">❌</td>
<td style="text-align: center;">❌</td>
<td style="text-align: center;">❌</td>
</tr>
<tr>
<td>Fine-grained sharing (grants, links, embeds)</td>
<td style="text-align: center;">✅</td>
<td style="text-align: center;">partial</td>
<td style="text-align: center;">❌</td>
<td style="text-align: center;">❌</td>
<td style="text-align: center;">❌</td>
<td style="text-align: center;">partial</td>
</tr>
<tr>
<td>Server-side outputs (Icecast/Snapcast)</td>
<td style="text-align: center;">✅</td>
<td style="text-align: center;">❌</td>
<td style="text-align: center;">❌</td>
<td style="text-align: center;">❌</td>
<td style="text-align: center;">(Spotify Connect, proprietary)</td>
<td style="text-align: center;">❌</td>
</tr>
<tr>
<td>External library import (S3, WebDAV, Jellyfin, TIDAL…)</td>
<td style="text-align: center;">✅</td>
<td style="text-align: center;">partial</td>
<td style="text-align: center;">❌</td>
<td style="text-align: center;">❌</td>
<td style="text-align: center;">❌</td>
<td style="text-align: center;">❌</td>
</tr>
<tr>
<td>Support for payments to artists</td>
<td style="text-align: center;">✅</td>
<td style="text-align: center;">❌</td>
<td style="text-align: center;">❌</td>
<td style="text-align: center;">❌</td>
<td style="text-align: center;">✅</td>
<td style="text-align: center;">✅</td>
</tr>
<tr>
<td>Support for subscriptions to fund platform maintainers</td>
<td style="text-align: center;">✅</td>
<td style="text-align: center;">❌</td>
<td style="text-align: center;">❌</td>
<td style="text-align: center;">❌</td>
<td style="text-align: center;">✅</td>
<td style="text-align: center;">✅</td>
</tr>
<tr>
<td>You own the catalog</td>
<td style="text-align: center;">✅</td>
<td style="text-align: center;">✅</td>
<td style="text-align: center;">✅</td>
<td style="text-align: center;">✅</td>
<td style="text-align: center;">❌</td>
<td style="text-align: center;">you can download the content you pay for</td>
</tr>
</tbody>
##
Quickstart
The fastest path is the Docker bootstrap script, which drops a docker-compose.yml, an nginx config, and starter config.toml/.env files into the current directory:
<code>curl -fsSL https://git.fabiomanganiello.com/songhive/raw/branch/main/docker/bootstrap.sh | sh
</code>
Set your user's UID/GID in .env (so the bind-mounted volumes stay yours), fill in the few required values in config.toml:
<code>[auth]
secret_key = "..." # python -c "import secrets; print(secrets.token_urlsafe(64))"
[storage]
local_path = "./data/media"
[federation]
enabled = false
# instance_domain = "music.example.com" # uncomment to join the fediverse
</code>
then:
<code>docker compose up
# Or, if you want to enable local HTTP stream mount points too
docker compose up --profile streams
</code>
Create the admin user:
<code>docker compose exec songhive songhive admin create-user \
 --username admin --email admin@example.com --password secret --admin
</code>
Open http://localhost:8000/ and start uploading. The web UI, Swagger UI (/swagger-ui/) and OpenAPI spec (/openapi.json) are all served by the same process. There's also a pip install songhive path (the PyPI package ships the built web UI), systemd units under config/systemd/, and an install.sh that wires the whole thing up — see the README for those.
Everything else — federation, Webmentions, RSS feeds, scrobbling keys, registration mode, bitrate caps — is a config knob, and most of it is enabled by default. All config.toml entries can also be overridden with SONGHIVE_* environment variables.
##
Under the hood
<li>Backend: FastAPI (REST) mounted inside Tornado via <code>a2wsgi</code> — Tornado natively handles WebSockets, audio streaming with range requests, and HTTP stream mountpoints, while FastAPI handles everything else. (There's a non-obvious reason for the explicit thread pool in the WSGI bridge: without it, a federated fetch that resolves back to your own instance deadlocks the event loop. The architecture doc tells the whole war story.)</li>
<li>Data: PostgreSQL (SQLite works for small setups) + SQLAlchemy 2 async, Pydantic v2 everywhere, Alembic migrations.</li>
<li>Async work: Celery + Redis with three queues — <code>celery</code> for interactive work, <code>scrobbles</code> for latency-sensitive submissions, and <code>bulk</code> for the per-item fan-out jobs (a fresh external library sync can enqueue tens of thousands of enrichment tasks; without the split they'd starve scrobbles and federation delivery for hours).</li>
<li>Storage: content-addressable files (SHA-256) with audio-only hashing, so tag/cover-art rewrites don't move files or invalidate hashes.</li>
<li>Frontend: Vue 3 + TypeScript + Pinia, fully i18n'd with RTL support.</li>
<li>Security posture: JWT + opaque rotating refresh tokens, double-submit CSRF, Redis sliding-window rate limiting, SSRF-guarded federation and Webmention fetches with redirect revalidation, Fernet-encrypted provider secrets, RFC 7807 error handling.</li>
<li>License: AGPL-3.0.</li>
##
Caveats, honestly
<li>It's a real stack: Postgres, Redis, a Celery worker, ffmpeg. The Docker compose file makes this a non-issue, but it's not a single static binary. It can run on a RaspberryPi 4 or 5 with decent storage if you want to run it for yourself and your family, but if you want to have more tracks and more users you may need a beefier machine.</li>
<li>Federation with the big platforms is only as good as ActivityPub support for audio — Mastodon renders playable audio attachments, but it treats <code>Audio</code> as a converted type, so Songhive also emits <code>Note</code> variants when you share a track as a post. The interop details with Akkoma, Funkwhale and friends are handled, but the fediverse music landscape is still young.</li>
<li>TIDAL imports federate metadata-only (a browse link, not hosted audio) — for obvious reasons the audio bytes stay with the provider.</li>
##
Links
<li>🏠 My personal instance: <a href="https://manganiello.music">manganiello.music</a></li>
<li>👤 My Fediverse handle: <a href="https://manganiello.music/@fabio">@npub1ajx…3p4q</a></li>
<li></> Code: <a href="https://github.com/blacklight/songhive">github.com/blacklight/songhive</a>
(canonical forge: <a href="https://git.fabiomanganiello.com/songhive">git.fabiomanganiello.com/songhive</a>)</li>
<li>🏗️ Architecture deep-dive:
<a href="https://git.fabiomanganiello.com/blacklight/songhive/src/branch/main/docs/ARCHITECTURE.md"><code>docs/ARCHITECTURE.md</code></a></li>
<li>🧩 Mopidy extension: <a href="https://github.com/blacklight/mopidy-songhive">mopidy-songhive</a></li>
https://s3.fabiomanganiello.com/fabio/screenshots/songhive/home-full.png
https://s3.fabiomanganiello.com/fabio/screenshots/songhive/home-federated.png
https://s3.fabiomanganiello.com/fabio/screenshots/songhive/subsonic-android.png
https://s3.fabiomanganiello.com/fabio/screenshots/songhive/listening-stats-1.png
https://s3.fabiomanganiello.com/fabio/screenshots/songhive/listening-stats-2.png
https://s3.fabiomanganiello.com/fabio/screenshots/songhive/artist-payment-form.png
https://s3.fabiomanganiello.com/fabio/screenshots/songhive/membership-form.png
https://s3.fabiomanganiello.com/fabio/screenshots/songhive/mastodon-integration.png
https://s3.fabiomanganiello.com/fabio/screenshots/songhive/track-share.png

2026-03-21 11:21:30 UTC

**[Support for post visibility in Madblog](https://blog.fabiomanganiello.com/article/support-for-post-visibility-in-madblog )**
#
Support for post visibility in Madblog
#madblog has now added support for *custom visibility* for your posts and articles.
You may not want everything you write to be published on your index or federated everywhere.
Madblog now allows you to easily tweak the audience of your posts.
##
Visibility levels
<thead>
<tr>
<th style="text-align: left;">Visibility Level</th>
<th style="text-align: center;">Blog Index</th>
<th style="text-align: center;"><code>/unlisted</code> Page</th>
<th style="text-align: center;">Reactions List</th>
<th>ActivityPub Targets</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left;"><code>public</code></td>
<td style="text-align: center;">✅</td>
<td style="text-align: center;">❌</td>
<td style="text-align: center;">✅</td>
<td><code>to: [Public]</code> <code>cc: [followers]</code></td>
</tr>
<tr>
<td style="text-align: left;"><code>unlisted</code></td>
<td style="text-align: center;">❌</td>
<td style="text-align: center;">✅</td>
<td style="text-align: center;">✅</td>
<td><code>to: [followers]</code> <code>cc: [Public]</code></td>
</tr>
<tr>
<td style="text-align: left;"><code>followers</code></td>
<td style="text-align: center;">❌</td>
<td style="text-align: center;">❌</td>
<td style="text-align: center;">❌</td>
<td><code>to: [followers]</code> <code>cc: []</code></td>
</tr>
<tr>
<td style="text-align: left;"><code>direct</code></td>
<td style="text-align: center;">❌</td>
<td style="text-align: center;">❌</td>
<td style="text-align: center;">❌</td>
<td><code>to: [mentions]</code> <code>cc: []</code></td>
</tr>
<tr>
<td style="text-align: left;"><code>draft</code></td>
<td style="text-align: center;">❌</td>
<td style="text-align: center;">❌</td>
<td style="text-align: center;">❌</td>
<td>Not federated</td>
</tr>
</tbody>
All the visibility levels (except for draft) map one-to-one with their corresponding meanings on the Fediverse.
<li>public: articles are rendered on the blog indexes and replies are rendered in the comments section.</li>
<li>unlisted: articles are rendered under the <code>/unlisted</code> page, replies are rendered in the comments section.</li>
<li>followers: articles are not rendered on the blog, replies are not rendered in the comments section (only visible to ActivityPub followers).</li>
<li>direct: articles are not rendered on the blog, replies are not rendered in the comments section (only visible to tagged ActivityPub users).</li>
<li>draft content is neither rendered on the blog nor federated.</li>
##
Default visibility
You can configure the default visibility level for all of your posts on a global level via config.yaml:
<code>default_visibility: public
</code>
Or MADBLOG_DEFAULT_VISIBILITY environment variable.
##
Per-post visibility
You can configure the visibility level of a post by using the visibility Markdown header:
<code># A private post
[//]: # (visibility: direct)
@alice@example.com only you should be able to see this message
</code>
##
ActivityPub constraints
If a post is federated then **YOU CANNOT** change its visibility level. This is a constraint on ActivityPub itself. You should delete and re-created the post with a different audience instead.
If a post was already federated and you move it to *Draft* then the previously federated version *will not be removed*. No changes that you apply while it's a draft will be published until you change the visibility level back, but the latest federated version will still be available. If you want to delete it, then you should delete the associated file.
##
Security observations
Remember that Madblog, by design, has **NO USERS**, **NO AUTHENTICATION** and **NO WRITE API**.
Everything lives on the file system, and every Markdown file in the supported folders will have a public URL.
It means that everyone with the URL can access the content.
Be mindful about *not sharing sensitive data*, even in drafts or private messages. And, if you can, use non-easy-to-guess filenames for posts you want to keep private.

2026-03-18 20:44:09 UTC

https://blog.fabiomanganiello.com/reply/the-local-tech-neighbourhood
A corollary to the concept of [small tech neighbourhood](https://blog.fabiomanganiello.com/article/the-small-tech-neighbourhood ) is the idea of *local tech communities*.
It's easy for folks like me, who have been self-hosting on computers in my closet since the time of high school, to lose track with the common non-tech person.
It's easy for us to say "*just self-host your Nextcloud, Matrix, XMPP, Mastodon, Searxng, Wallabag etc.*", adding a "*it's just a docker run command*".
I've also seen "just run your f*cking website" articles get to the top of HackerNews.
But then I thought: imagine if it was, say, the bakery industry rather than the software industry to go through a process of #enshittification.
Imagine that buying your bread or croissant tomorrow requires a $100/month Bread+ subscription with plenty of upsells, an age verification process that requires you to send your passport or retina scan to the Big Bread consortium, a tracking system that measures exactly how much bread you eat at home, and that keeps selling your eating habits to whoever wants to purchase them - all while your bread quality gets progressively worse over time, and the oligopoly that holds it, after acquiring or putting out of business any credible competitors, starts experimenting also with selling expired products.
Of course people would be outraged.
But many, no matter how outraged they are, will just swallow the bitter pill and stick with the Bread+ subscription (perhaps because they don't care enough yet to trigger a change in their habits, perhaps because they have other priorities and battles to fight), hoping that the next change to the T&C won't make it even worse.
And some will instead start looking for alternatives.
Would it make sense for a professional baker who's been in the business for decades to tell those folks "just bake your own f*cking bread" - and then complain that not enough are moving out of the Bread+ walled garden?
Or perhaps would it make more sense for that baker to volunteer for a competitive price to sell their bread to its friends, family and local community?
We all know that running your own stuff on your own machines is the best way to avoid enshittification. But not everyone will do it, nor they are supposed to do it.
People live different lives, have different priorities and choose different battles. Any pragmatic human must at some point delegate some tasks - that's how modern societies were born. Real autarchy in complex society is nothing more than a pipe dream. We don't judge those outside of our area of competencies for not being able or willing to perform a certain task, no matter how trivial that looks to us.
An average neighbourhood has someone good enough at baking that they can sell their products to their local community.
And howadays perhaps it also has someone good enough with computers that they can probably run on an old laptop or unused VPS stuff like a small Matrix server, a GoToSocial instance, a Nextcloud instance or an Immich server.
And they could probably serve that to small local groups of 10-20 people for something like $10/month (and at low volumes those services usually don't even require much maintenance).
It can be $100/200 month that can abundantly cover the cost of a small VPS, let alone the cost of running a miniPC at home.
It'd be a bargain for the subscribers too - nowadays for $10/month you don't even get a Netflix subscription, let alone a complete cloud alternative with no trackers and no ads.
It can even be a reliable source of income for IT folks in areas that would otherwise not provide other viable employment solutions.
In a healthy society with a high level of immunity against enshittification, your local self-hoster should probably become the digital equivalent of your local baker or your local pub.
#smalltech #techneighbourhoods #selfhosting

2026-03-18 13:42:59 UTC

https://blog.fabiomanganiello.com/reply/unlisted-posts
The latest version of #madblog introduces a separate page, under /unlisted, for posts that the author can send to the Fediverse (or simply keep in a separate area of their blog) without publishing them on the index.
This is useful for quick thoughts and interactions. Worth enough to mention, but not enough to deserve their own dedicate article on the blog frontpage.
To create an unlisted post, simply create a Markdown file under /replies/ with no like-of and reply-to metadata headers:
<code>cd $MADBLOG_DATADIR
mkdir -p replies
cat <<EOF > replies/unlisted-post.md
# My first unlisted post
I thought that it'd be cool to share with my followers on Mastodon that now I can trace likes and replies with git bisect.
I'll also tag @friend@nerds.tech because he'll probably think it's cool.
</code>
Save the file, then you will find your post on the /unlisted page.

2026-03-16 23:56:07 UTC

https://blog.fabiomanganiello.com/reply/git-up-your-blog
That oddly satisfying feeling of browsing your blogging and social media history with git log and git grep #madblog #activitypub #indieweb
[[Screenshot of git log from a terminal directory. It's executed from my blog directory populated with Markdown files and served via Madblog. It shows all of my replies, posts, modifications and reactions as commits.](https://s3.fabiomanganiello.com/fabio/img/madblog-git-log-screenshot.png )]
https://s3.fabiomanganiello.com/fabio/img/madblog-git-log-screenshot.png

2026-03-16 23:13:22 UTC

https://blog.fabiomanganiello.com/reply/None/git-log-for-your-blog
That oddly satisfying feeling of browsing your blogging and social media history with git log and git grep #madblog #activitypub #indieweb
[[Screenshot of git log from a terminal directory. It's executed from my blog directory populated with Markdown files and served via Madblog. It shows all of my replies, posts, modifications and reactions as commits.](https://s3.fabiomanganiello.com/fabio/img/madblog-git-log-screenshot.png )]
https://s3.fabiomanganiello.com/fabio/img/madblog-git-log-screenshot.png

2026-03-15 01:59:59 UTC

**[Federated Replies and Reactions in Madblog](https://blog.fabiomanganiello.com/article/Federated-replies-and-reactions-in-Madblog )**
**Engage with the Web from plain text files**
[Madblog](https://git.fabiomanganiello.com/madblog ) is founded on a simple principle: a blog is just a collection of #markdown files in a folder. No databases, no logins, no client-side bloat — just files.
The recently implemented support for both [Webmentions](https://blog.fabiomanganiello.com/article/webmentions-with-batteries-included ) and [ActivityPub](https://blog.fabiomanganiello.com/article/Madblog-federated-blogging-from-markdown ) add an extra appeal to this approach: now those text files can federate, they can send mentions to Wordpress blogs or Mastodon accounts, and you can visualize mentions, comments and reactions from other corners of the Web directly under your articles.
But after receiving in the past few days a bunch of reactions on [my blog](https://blog.fabiomanganiello.com ) that I couldn't interact with, which forced me to fall back on [my standard Fediverse account](https://manganiello.eu/@fabio ) to send replies and likes, I've decided to take the "[*everything is a file*](https://en.wikipedia.org/wiki/Everything_is_a_file )" philosophy a step further.
Now from #madblog you can also **reply to comments** and **react to posts** across the Fediverse - all from plain text files in your content folder.
##
Replying to Comments
When someone comments on your article from Mastodon or another ActivityPub-compatible services, their message appears on your blog.
Now you can also respond directly from your blog.
Or you can reply to any other post on the Fediverse or mention anyone, without those posts cluttering your blog's front page (I've learned to avoid this fatal design mistake made by e.g. [Medium](https://medium.com/ )).
###
How it works
Create a Markdown file under replies/<article-slug>/:
<code> [//]: # (reply-to: https://mastodon.social/@alice/123456789)
Thanks for the kind words, Alice! I'm glad the tutorial helped.
@alice@mastodon.social
</code>
Save the file, and Madblog automatically:
<li>Publishes your reply to the Fediverse as a threaded response</li>
<li>Notifies Alice on her Mastodon instance</li>
<li>Displays the reply on your blog, nested under her original comment</li>
Your reply lives in your content folder. Just like with your articles, you can version replies and reactions on git, synchronize them over [SyncThing](https://syncthing.net/ ) or [Nextcloud Notes](https://nextcloud.com/ ), or run some analysis scripts on them that would just operate on text files.
###
Replying to replies
Conversations can go as deep as you want. Reply to a reply by pointing reply-to at the previous message's URL:
<code> [//]: # (reply-to: https://mastodon.social/@alice/123456790)
Great question! I'll write a follow-up post about that.
@alice@mastodon.social
</code>
The threading is preserved both on your blog and across the Fediverse.
[[Example of a nested thread rendered on Madblog](https://s3.fabiomanganiello.com/fabio/img/madblog-replies-1.png )]
(I hope that @npub1vm0…3lyd and @npub1xse…lgk3 won't mind for using a screenshot from their conversation on my blog 🙂)
###
Remember to mention your mentions
An important implementation note: if you're replying to someone else's ActivityPub post, it's important that you also mention them in the reply, otherwise your reply will be rendered under their comment but they may not be notified.
Usually you don't have to worry about this on Mastodon because the UI will automatically pre-fill the participating accounts in a sub-thread when you hit *Reply*.
But this is something to keep in mind when your posts are just text files.
##
Your replies are articles in their own right
Even though anything under replies/ won't appear on your blog's home page, it doesn't mean that it must be rendered just like a humble rectangle in a crowded comments section.
By clicking *View full reply* you get redirected to a separate page where the reply is rendered as a blog article, and its comments sections consists in the sub-tree of the reactions that spawned from that specific reply.
[[Example of a Madblog reply rendered as a blog article, with its own sub-thread of reactions](https://s3.fabiomanganiello.com/fabio/img/madblog-replies-2.png )]
##
Liking Posts
Sometimes a reply is too much — you just want to show appreciation. Now you can "like" any post on the Fediverse with a simple metadata header.
###
Standalone likes
Create a file under replies/ with just a like-of header:
<code> [//]: # (like-of: https://mastodon.social/@bob/987654321)
</code>
This publishes a Like activity to the Fediverse. Bob sees the notification,
and your blog records the interaction.
###
Like and comment
Want to like *and* say something? Combine both:
<code> [//]: # (like-of: https://mastodon.social/@bob/987654321)
[//]: # (reply-to: https://mastodon.social/@bob/987654321)
This is such a great point! Bookmarking for later.
@bob@mastodon.social
</code>
Bob gets both the like and your reply as a threaded response.
##
Unlisted Posts
Not everything needs to appear on your blog's front page. Files under replies/ without reply-to and like-of headers become "unlisted" posts — they're published to the Fediverse but don't clutter your blog index.
Perfect for quick thoughts, threads, or conversations that don't warrant a full article.
<code> [//]: # (title: Thoughts of the day)
Quick thought: I've been experimenting with writing all my Fediverse posts
as Markdown files. It's oddly satisfying to `git log` my social media history.
</code>
##
Guestbook Replies
Your blog's guestbook works the same way. Reply to guestbook entries by placing files under replies/_guestbook/:
<code> [//]: # (reply-to: https://someone.blog/mention/123)
@alice@example.com welcome! Thanks for stopping by.
</code>
##
Editing and Deleting
Changed your mind? Edit the file and an Update activity is sent. Delete the file and your reply is removed from the Fediverse too.
Accidentally liked something? Remove the like-of line (or delete the file) and an Undo Like is published.
Your content, your rules.
##
Getting Started
<li>Enable ActivityPub in your <code>config.yaml</code>:</li>
<code>link: https://blog.example.com
enable_activitypub: true
activitypub_username: blog
# Only specify these if you want your ActivityPub domain to be different from your blog domain
# activitypub_link: https://example.com
# activitypub_domain: example.com
</code>
<li>Install Madblog</li>
<li>From <code>pip</code>:</li>
<code>pip install madblog
</code>
<li>From Docker:</li>
<code>docker pull quay.io/blacklight/madblog
</code>
<li>Run Madblog from your Markdown folder (it is recommended that your articles are stored under <code><data-dir>/markdown</code>):</li>
<li>From a <code>pip</code> installation:</li>
<code>madblog /path/to/data
</code>
<li>From Docker:</li>
<code>docker run -it \
 -p 8000:8000 \
 -v "/path/to/config.yaml:/etc/madblog/config.yaml" \
 -v "/path/to/data:/data" \
 quay.io/blacklight/madblog
</code>
<li>Any text file you create under <code>markdown/</code> becomes a blog article. Any text file you create under <code>replies/</code> becomes an unlisted post, a reply or a like reaction.</li>
Check the [README](https://git.fabiomanganiello.com/madblog ) for detailed configuration options.
Happy blogging!
https://s3.fabiomanganiello.com/fabio/img/madblog-replies-1.png
https://s3.fabiomanganiello.com/fabio/img/madblog-replies-2.png

2026-03-14 10:53:46 UTC

- reply

good catch!
It wasn't intentional, I had simply forgotten to apply to replies the same quote policy I implemented for articles.
It should [be working now](https://git.fabiomanganiello.com/madblog/commit/8c12db13da124f4e79a42c70689ccfbfd2983f02 ) - thanks for the heads up 🙂

2026-03-14 09:15:48 UTC

- reply

and now with support for #markdown based [replies](https://git.fabiomanganiello.com/madblog#author-replies ) too 🙂

2026-03-10 14:53:36 UTC

**[Madblog: A Markdown Folder That Federates Everywhere](https://blog.fabiomanganiello.com/article/Madblog-federated-blogging-from-markdown )**
**A lightweight blogging engine based on text files, with native Fediverse and IndieWeb support**
I started working on [Madblog](https://git.fabiomanganiello.com/madblog ) a few years ago.
I wanted a simple blogging platform that I could run from my own Markdown files. No intermediaries. No bloated UI. No JavaScript. No databases and migration scripts. No insecure plugins. Just a git folder, an Obsidian vault or a synchronized SyncThing directory, and the ability to create and modify content by simply writing text files, wherever I am.
Drop a Markdown file in the directory, and it's live. Edit it, and the changes propagate. Delete it, and it's gone.
It's been running my [personal blog](https://blog.fabiomanganiello.com ) and the [Platypush blog](https://blog.platypush.tech ) for a while now.
With the new release, #madblog now gets a new superpower: it supports federation, interactions and comments both through:
<li><a href="https://indieweb.org/Webmention">Webmentions</a> - already implemented some weeks ago, you can also check out the <a href="https://blog.fabiomanganiello.com/article/webmentions-with-batteries-included">previous blog article</a></li>
<li><a href="https://indieweb.org/ActivityPub">ActivityPub</a></li>
Webmentions allow your site to mention and be mentioned by other sites that also implement them - like any WordPress blog with the [Webmention plugin](https://wordpress.org/plugins/webmention/ ), or link aggregators like [Lemmy](https://join-lemmy.org/ ) or [HackerNews](https://news.ycombinator.com/ ). Interactions with any of your pages will be visible under them.
#activitypub support allows Madblog to fully federate with Mastodon, Pleroma, Misskey, Friendica or any other #fediverse instance. It turns your blog into a federated handle that can be followed by anyone on the Fediverse. It gives you the ability to mention people on the Fediverse directly from your text files, and get replies to your articles directly from Mastodon, get your articles boosted, shared and quoted like any other Mastodon post.
##
Demos
These blogs are powered by Madblog:
<li><a href="https://blog.fabiomanganiello.com">blog.fabiomanganiello.com</a> — Fediverse handle: <a class="activitypub-mention" href="https://manganiello.blog/@fabio">@npub17w6…48ey</a></li>
<li><a href="https://blog.platypush.tech">blog.platypush.tech</a> — Fediverse handle: <a class="activitypub-mention" href="https://platypush.tech/@blog">@npub1pqj…al0g</a></li>
You can follow them from Mastodon (or any other Fediverse client), reply to articles directly from your instance, boost them, or quote them. You can also interact via [Webmentions](https://indieweb.org/Webmention ): link to an article from your own site, and if your site supports Webmentions, the mention will show up as a response on the original post. These blogs also have a [Guestbook](https://blog.fabiomanganiello.com/guestbook ) — mention the blog's Fediverse handle or send a Webmention to the home page, and your message appears on a public guest registry.
##
How Does It Compare?
If you've looked into federated blogging before, you've likely come across a few options:
<li><a href="https://writefreely.org/">WriteFreely</a> is probably the closest alternative — a minimalist, Go-based platform with ActivityPub support. It's well-designed, but it uses a database (SQLite or MySQL), has its own (very minimal) editor, and doesn't support Webmentions. Additionally, it lacks many features that are deal-breakers for me.</li>
<li>No export of all the content to Markdown, nor ability to run my blog from my Nextcloud Notes folder or Obsidian vault.</li>
<li>No support for LaTeX or Mermaid diagrams.</li>
<li>No support for federated interactions - any interaction with your articles on the Fediverse is simply lost.</li>
<li>The UI is minimalist and not necessarily bad, but not even sufficiently curated for something like a blog (narrow width, Serif fonts not optimized for legibility, the settings and admin panels are a mess...).</li>
<li>No support for moderation / content blocking.</li>
<li>
No support for federated hashtags.
</li>
<li>
<a href="https://wordpress.org/">WordPress</a> with ActivityPub and Webmention plugins can technically do what Madblog does, but it's a full CMS with a database, a theme engine, a plugin ecosystem, and a much larger attack surface. If all you need is a blog, it's overkill.
</li>
<li>
<a href="https://joinplu.me/">Plume</a> and <a href="https://friendi.ca/">Friendica</a> offer blogging with federation, but they're full social platforms, not
lightweight publishing tools.
</li>
Madblog sits in a different niche: it's closer to a static-site generator that happens to speak federation protocols. It implements a workflow like "write Markdown, push to server, syndicate everywhere".
##
Getting Started
###
Docker Quickstart
<code>mkdir -p ~/madblog/markdown
cat <<EOF > ~/madblog/markdown/hello-world.md
# Hello, Fediverse!
This is my first post on [Madblog](https://git.fabiomanganiello.com/madblog)!
EOF
docker run -it \
 -p 8000:8000 \
 -v "$HOME/madblog:/data" \
 quay.io/blacklight/madblog
</code>
Open http://localhost:8000. That's it — you have a blog.
The default Docker image (quay.io/blacklight/madblog) is a minimal build (< 100 MB) that includes everything except LaTeX and Mermaid rendering. If you need those, build the full image from source:
<code>git clone https://git.fabiomanganiello.com/madblog
cd madblog
docker build -f docker/full.Dockerfile -t madblog .
</code>
See the [full Docker documentation](https://git.fabiomanganiello.com/madblog/src/branch/main/README.md#running-madblog-in-docker ) for details on mounting config files and ActivityPub keys.
###
Markdown structure
Since there's no database or extra state files involved, the metadata of your articles is also stored in Markdown.
Some things (like title, description) can be inferred from the file name, headers of your files etc., creation date defaults to the creation timestamp of the file and author and language are inherited from your config.yaml.
A full customized header would look like this:
<code> [//]: # (title: Title of the article)
[//]: # (description: Short description of the content)
[//]: # (image: /img/some-header-image.png)
[//]: # (author: Author Name <https://author.me>)
[//]: # (author_photo: https://author.me/avatar.png)
[//]: # (language: en-US)
[//]: # (published: 2022-01-01)
...your Markdown content...
</code>
###
Key Configuration
Madblog reads configuration from a config.yaml in your content directory. Every option is also available as an environment variable with a MADBLOG_ prefix — handy for Docker or CI setups.
A minimal config to get started:
<code>title: My Blog
description: Thoughts on tech and life
link: https://myblog.example.com
author: Your Name
</code>
Or purely via environment variables:
<code>docker run -it \
 -p 8000:8000 \
 -e MADBLOG_TITLE="My Blog" \
 -e MADBLOG_LINK="https://myblog.example.com" \
 -e MADBLOG_AUTHOR="Your Name" \
 -v "$HOME/madblog:/data" \
 quay.io/blacklight/madblog
</code>
See [config.example.yaml](https://git.fabiomanganiello.com/madblog/src/branch/main/config.example.yaml ) for the full reference.
>
> It is advised to keep all of your Markdown content under <data-dir>/markdown> ,
especially if you enable federation, in order to keep the Markdown folder
tidy from all the auxiliary files generated by Madblog.
>
##
Webmentions
[Webmentions](https://indieweb.org/Webmention ) are the IndieWeb's answer to trackbacks and pingbacks — a W3C standard that lets websites notify each other when they link to one another. Madblog supports them natively, both inbound and outbound.
When someone links to one of your articles from a Webmention-capable site, your blog receives a notification and renders the mention as a response on the article page. Going the other way, when you link to an external URL in your Markdown and save the file, Madblog automatically discovers the target's Webmention endpoint and sends a notification — no manual step required. All mentions are stored as Markdown files under your content directory (mentions/incoming/<post-slug>/), so they're version-controllable and easy to inspect.
You can enable pending-mode for moderation (webmentions_default_status: pending), or use the blocklist/allowlist system to filter sources by domain, URL, or regex. Webmentions are enabled by default — if you're running Madblog locally for testing, set enable_webmentions: false to avoid sending real notifications to external sites.
##
ActivityPub Federation
[ActivityPub](https://www.w3.org/TR/activitypub/ ) is the protocol that powers the Fediverse — Mastodon, Pleroma, Misskey, and hundreds of other platforms. Madblog implements it as a first-class feature: enable it, and your blog becomes a Fediverse actor that people can follow, reply to, boost, and quote.
Enable it in your config:
<code>enable_activitypub: true
activitypub_username: blog
activitypub_private_key_path: /path/to/private_key.pem
</code>
Madblog will generate an RSA keypair on first start if you don't provide one. Once enabled, your blog gets a Fediverse handle (@blog@yourdomain.com), a WebFinger endpoint for discovery, and a full ActivityPub actor profile. New and updated articles are automatically delivered to all followers' timelines.
Here's what federation looks like in practice:
<li>Receiving mentions: when someone mentions your blog's Fediverse handle in a public post (not as a reply to a specific article), the mention shows up on your <a href="#guestbook">Guestbook</a> page.</li>
<li>Receiving replies, likes, boosts, and quotes: interactions targeting a specific article are rendered below that article — replies as threaded comments, likes/boosts/quotes as counters and cards. All stored as JSON files on disk.</li>
<li>Sending mentions: just write the fully-qualified handle in your Markdown (<code>@npub19tr…plwd</code>) and save the file. Madblog resolves the actor via WebFinger and delivers a proper ActivityPub <code>Mention</code> tag — the mentioned user gets a notification on their instance.</li>
<li>Federated hashtags: hashtags in your articles (<code>#Python</code>, <code>#Fediverse</code>) are included as ActivityPub <code>Hashtag</code> tags in the published object. Followers who track those hashtags on their instance will see your posts in their filtered feeds.</li>
<li>Custom profile fields: configure additional profile metadata (verified links, donation pages, git repos) that show up on your actor's profile as seen from Mastodon and other Fediverse clients:</li>
yaml
activitypub_profile_fields:
Git repository: <https://git.example.com/myblog>
Donate: <https://liberapay.com/myprofile>
The federation layer also exposes a read-only subset of the [Mastodon API](https://docs.joinmastodon.org/methods/ ), so Mastodon-compatible clients and crawlers can discover the instance, look up the actor, list published statuses, and search for content — with no extra configuration.
Madblog also supports advanced ActivityPub features like split-domain setups (e.g. your blog at blog.example.com but your Fediverse handle at @blog@example.com), configurable object types (Note for inline rendering on Mastodon vs. Article for link-card previews), and quote policies ([FEP-044f](https://codeberg.org/fediverse/fep/src/branch/main/fep/044f/fep-044f.md ), so Mastodon users can quote your articles too).
##
LaTeX and Mermaid
Madblog supports server-side rendering of LaTeX equations and Mermaid diagrams directly in your Markdown files — no client-side JavaScript required.
**LaTeX** uses latex + dvipng under the hood. Inline expressions use conventional LaTeX markers:
<code>The Pythagorean theorem states that $c^2 = a^2 + b^2$.
$$
E = mc^2
$$
</code>
**Mermaid** diagrams use standard fenced code blocks. Both light and dark theme variants are rendered at build time and switch automatically based on the reader's color scheme:
<code> ```mermaid
 graph LR
 A[Write Markdown] --> B[Madblog renders it]
 B --> C[Fediverse sees it]
 ```
</code>
Install Mermaid support with pip install "madblog[mermaid]" or use the full Docker image. Rendered output is cached, so only the first render of each block is slow.
##
Tags and Categories
Tag your articles with hashtags — either in the metadata header or directly in the body text:
<code># My Article
This post is about #Python and the #Fediverse.
</code>
Madblog builds a tag index at /tags, with per-tag pages at /tags/<tag>. Hashtags from incoming Webmentions are also indexed. Folders in your content directory act as categories — if you organize files into subdirectories, the home page groups articles by folder.
##
Feed Syndication
Madblog generates both RSS and Atom feeds at /feed.rss and /feed.atom. You can control whether feeds include full article content or just descriptions (short_feed: true), and limit the number of entries (max_entries_per_feed: 10). limit and offset parameters are also supported for pagination.
##
Aggregator Mode
Madblog can also pull in external RSS/Atom feeds and render them alongside your own posts on the home page — useful for affiliated blogs, or even as a self-hosted feed reader:
<code>external_feeds:
 - https://friendsblog.example.com/feed.atom
 - https://colleaguesblog.example.com/feed.atom
</code>
##
Guestbook
The guestbook (/guestbook) is a dedicated page that aggregates public interactions — Webmentions targeting the home page and Fediverse mentions of your blog actor that aren't replies to specific articles. Think of it as a public guest registry, or a lo-fi comment section for your blog as a whole. Visitors can leave a message by mentioning your Fediverse handle or sending a Webmention. It can be disabled via enable_guestbook=0.
##
View Modes
The home page supports three layouts:
<li><code>cards</code> (default) — a responsive grid of article cards with images</li>
<li><code>list</code> — a compact list with titles and dates</li>
<li><code>full</code> — a scrollable, WordPress-like view with full article content inline</li>
Set it in your config (view_mode: cards) or override at runtime with ?view=list.
##
Moderation
Madblog ships with a flexible moderation system that applies to both Webmentions and ActivityPub interactions. You can run in **blocklist mode** (reject specific actors) or **allowlist mode** (accept only specific actors), with pattern matching by domain, URL, ActivityPub handle, or regex:
<code>blocked_actors:
 - spammer.example.com
 - "@troll@evil.social"
 - /spam-ring\.example\..*/
</code>
Moderation rules also apply retroactively — interactions already stored are filtered at render time. Blocked ActivityPub followers are excluded from fan-out delivery and hidden from the public follower count, but their records are preserved so they can be automatically reinstated if you change your rules.
##
Email Notifications
Configure SMTP settings and Madblog will notify you by email whenever a new Webmention or ActivityPub interaction arrives — likes, boosts, replies, mentions, and quotes:
<code>author_email: you@example.com
smtp_server: smtp.example.com
smtp_username: you@example.com
smtp_password: your-password
</code>
##
Progressive Web App
Madblog is installable as a PWA, with offline access and a native-like experience on supported devices. A service worker handles stale-while-revalidate caching with background sync for retries.
##
Raw Markdown Access
Append .md to any article URL to get the raw Markdown source:
<code>https://myblog.example.com/article/my-post.md
</code>
Useful for readers who prefer plain text, or for tools that consume Markdown directly.
##
Reusable Libraries
Two key subsystems of Madblog have been extracted into standalone, reusable Python libraries. If you're building a Python web application and want to add decentralized federation support, you can use them directly — no need to adopt Madblog itself.
###
Webmentions
[Webmentions](https://git.fabiomanganiello.com/webmentions ) is a general-purpose Python library for sending and receiving Webmentions. It comes with framework adapters for FastAPI, Flask, and Tornado, pluggable storage backends (SQLAlchemy or custom), filesystem monitoring for auto-sending mentions when files change, full microformats2 parsing, and built-in HTML rendering for displaying mentions on your pages.
Adding Webmentions to a FastAPI app:
<code>from fastapi import FastAPI
from webmentions import WebmentionsHandler
from webmentions.storage.adapters.db import init_db_storage
from webmentions.server.adapters.fastapi import bind_webmentions
app = FastAPI()
storage = init_db_storage(engine="sqlite:////tmp/webmentions.db")
handler = WebmentionsHandler(storage=storage, base_url="https://example.com")
bind_webmentions(app, handler)
</code>
That's it — your app now has a /webmentions endpoint for receiving mentions,
a Link header advertising it on every response, and a storage layer for
persisting them. See the
[full documentation](https://git.fabiomanganiello.com/webmentions/src/branch/main/README.md )
for details on sending mentions, custom storage, moderation, and rendering.
###
Pubby
[Pubby](https://git.fabiomanganiello.com/pubby ) is a general-purpose Python library for adding ActivityPub federation to any web application. It handles inbox processing, outbox delivery with concurrent fan-out, HTTP Signatures, WebFinger/NodeInfo discovery, interaction storage, a Mastodon-compatible API, and framework adapters for FastAPI, Flask, and Tornado.
Adding ActivityPub to a FastAPI app:
<code>from fastapi import FastAPI
from pubby import ActivityPubHandler, Object
from pubby.crypto import generate_rsa_keypair
from pubby.storage.adapters.db import init_db_storage
from pubby.server.adapters.fastapi import bind_activitypub
app = FastAPI()
storage = init_db_storage("sqlite:////tmp/pubby.db")
private_key, _ = generate_rsa_keypair()
handler = ActivityPubHandler(
storage=storage,
actor_config={
"base_url": "https://example.com",
"username": "blog",
"name": "My Blog",
"summary": "A blog with ActivityPub support",
},
private_key=private_key,
)
bind_activitypub(app, handler)
# Publish a post to all followers
handler.publish_object(Object(
id="https://example.com/posts/hello",
type="Note",
content="Hello from the Fediverse!",
url="https://example.com/posts/hello",
attributed_to="https://example.com/ap/actor",
))
</code>
Optionally, you can also expose a Mastodon-compatible API so that Mastodon clients and crawlers can discover your instance and browse statuses:
<code>from pubby.server.adapters.fastapi_mastodon import bind_mastodon_api
bind_mastodon_api(
app,
handler,
title="My Blog",
description="A blog with ActivityPub support",
)
</code>
Both libraries follow the same design philosophy: provide the protocol plumbing so you can wire it into your existing application with minimal ceremony. Storage is pluggable (SQLAlchemy, file-based, or bring-your-own), framework binding is a single function call, and the core logic is framework-agnostic. See the full documentation for [Pubby](https://git.fabiomanganiello.com/pubby/src/branch/main/README.md ) and [Webmentions](https://git.fabiomanganiello.com/webmentions/src/branch/main/README.md ).
##
Links
<li><a href="https://git.fabiomanganiello.com/madblog">Madblog</a> (<a href="https://github.com/blacklight/madblog">Github mirror</a>)</li>
<li><a href="https://git.fabiomanganiello.com/webmentions">Webmentions</a> (<a href="https://github.com/blacklight/webmentions">Github mirror</a>)</li>
<li><a href="https://git.fabiomanganiello.com/pubby">Pubby</a> (<a href="https://github.com/blacklight/pubby">Github mirror</a>)</li>
Madblog is open-source under the AGPL-3.0-only license. The source code, issue tracker, and full documentation are available at [git.fabiomanganiello.com/madblog](https://git.fabiomanganiello.com/madblog ).