Publ

Not to be confused with publ micropub client.

Publ is a dynamic publishing system written in Python. It is billed as "like a static site generator, only dynamic." It is primarily developed by fluffy.

Its design is based on static publishing systems such as Jekyll or Pelican, but rather than generate static HTML content, it instead dynamically maps index and entry views to page/entry content based on metadata. It's specifically designed to allow for heterogeneous types of content; for example, the author's site uses the same publishing framework to provide vastly-different presentation and, in some cases, navigation mechanisms for disparate content types such as music, comics, art, and blogs.

It's also designed to keep "legacy" links intact; for example, an entry or category view can claim ownership of an older URL, and it's relatively simple to add regular expression-based URL rewriting as well. Further, if an entry is moved to a different part of the site, old links to its prior location(s) will be automatically redirected to the new permalink.

Another core tenet is that images are rendered based on the page template's requirements, and image renditions support high-DPI displays by default. Individual entries can also override the template rules as necessary, and can even specify different overrides based on which template is rendering it.

Publ is also built to support IndieWeb protocols. For example, the beesbuzz.biz templates support microformats, Atom (including WebSub), Webmention (both outgoing and incoming, via webmention.io and client-side JavaScript), and ActivityPub via Bridgy Fed. Outgoing push notifications are handled by Pushl, a companion app. Additionally, it has an IndieAuth token endpoint with support for IndieAuth Ticket Auth.

Publ is provided as a Python library that is installable via PyPI, and can run on any WSGI-based hosting (including Heroku and Dreamhost).

Core principles

Publ should be trivially deployable on a new system; there should never be any difficulty in migrating to a new server beyond deploying the content
- Relatedly, a site should be able to horizontally scale by deploying it to multiple systems behind a load balancer, or through an Anycast fleet, or should allow for migration to happen transparently during slow DNS propagation
Publ itself should be as close to stateless as possible; the database is not a source of ground truth, it is just an index into the filesystem, which is the source of ground truth; user authentication should be managed using signed cookies and not by server-side session storage
Publ should be agnostic to the content management technology; it shouldn't care how the data is managed or deployed; users are free to use whatever content deployment mechanism works the best for them (be it git, sshfs, FTP, ssh + vi, rsync, or a web-based content editor)
Publ should only worry about the concerns of publishing content to the web; managing other interactions (such as Webmention, WebSub, ActivityPub, comments, etc.) should be offloaded onto (stateful) technology that is purpose-built to handle those things
Publ must not dictate the structure of one's website, the types of posts which can be made, the navigational hierarchies, the archive layout, and so on; ideally it would not dictate the URI schema either (but that is currently a failed goal, as a matter of practicality more than anything else)
Publ URIs should be humane; they must be human-readable, entry IDs must be short enough to be memorable or at least repeatable, and it must be possible to always go to view an entry knowing only the ID
Entry and archive pages should be stable; any link to an existing URI should always show the relevant content at the time the page was last accessed; if a search engine indexed an archive page, then the same content should always be visible from that same page's archived URI; an old URI for a moved entry should redirect to its current location

Design inspirations

MovableType — the CMS that fluffy used from 2001 thru 2018; particularly the publishing model and archive/navigational flexibility (and the possibility of building humane URLs), but with a desire to escape its rigid template system (and the necessary hacks to get around it), its fragile data storage, and its inflexible image renditions
Tumblr — particularly in how templates and image renditions work, but hoping to avoid its inflexibility, its rigid post-type schema, and its inhumane URLs

Major features

Template-based image renditions

Images are rendered by the template, so that different views of the same content can get different sizes, crop methods, and so on. Images can even be configured to have different thumbnails/crops based on the template that's rendering them. Individual images can also be configured with different quality values or even output file formats.

The Markdown image syntax has also been extended to allow for image sets, so that templates can opt to only show, for example, the first 3 images in an image set, followed by a "read more" link that indicates how many more images are available.

There is also special support for generating CSS shape-outside rules so that images can be floated with tight wrapping.

Private Entries

Publ has the ability to make private posts which require logging in via some sort of identity provider to become known. It has support for a number of authentication mechanisms via Authl, including emailed magic links, Mastodon, IndieAuth/IndieLogin, and Twitter.

Access control is fine-grained; the owner of the site can declare various hierarchical groups and can have access rules that relate to those groups. For example, an entry can have metadata like:

Auth: friends https://example.com/~fred !bob@example.com !https://mastodon.example.com/@alice !family

which would mean "allow friends to see it, as well as Fred, but not Bob or Alice or anyone in the family group."

There are also provisions for allowing access to anyone who is logged in (using the special * group), and also restricting them to those who aren't logged in (using !*).

Some sites using Publ

beesbuzz.biz, fluffy's own website
Mullins Molecular Retrovirology Lab, an academic research lab
Novembeat, an annual song-a-day initiative