Articles (notes with a title) move from /note/<slug> to /article/<slug>; the other prefix 301-redirects. New articles take their slug from the title (mp-slug still wins; notes keep timestamp slugs). A Micropub update that adds or removes a title answers 201 with the new Location. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
4.0 KiB
4.0 KiB
ADR-076: Article titles and summaries stored apart from the text
Status
Accepted (v2.16.0, 2026-11-11)
Article URLs (/article/<slug>) and title slugs: ADR-077 (v2.17.0).
Supersedes the v2.3.3 design (micropub-title-and-source-url)
and Q22's "a note has a title when its content starts with #". Amends
ADR-014 (feed item titles) and ADR-040 (p-name and p-summary).
Context
An IndieWeb article is an h-entry with a name that isn't just the start of
its content (W3C Post Type Discovery). Since v1.2.0, StarPunk marked an article
by a # Heading first line in the Markdown, and v2.3.3 stored a Micropub name
as that heading. A review against IndieWeb practice found four gaps:
- Feeds repeated an article's title: the item title, then the same heading rendered at the top of the content.
- Every feed item had a title, made from a note's first line (or the date), so feed readers showed notes as headlines and couldn't tell them from articles.
- Micropub
summarywas used only whencontentwas missing; sent together with content, it was dropped. - Any note that happened to start with a heading became an article, and its
q=sourcechanged from what the client sent. Micropub and mf2 treatnameandcontentas separate properties.
Decision
- Columns.
notes.titleandnotes.summary(migration 023). A note with a title is an article; its Markdown file holds only the body. A heading in the body is just a heading. - Moving existing titles. Migration 023 has a Python data step
(
migrations.DATA_MIGRATIONS) that runs once, in the migration's transaction: for each note whose file starts with a heading (split_title, trashed files included), it moves the heading intotitle, rewrites the file and updatescontent_hash, then emptiesnotes_ftsso startup rebuilds it. If anything fails, the changed files are written back and the transaction is rolled back, so 023 is retried on the next start. Tying it to the migration matters: run on every start it would turn new notes' headings into titles. - Micropub.
name→title;summary→summarywhencontentis also sent. A summary on its own is still stored as the content, which is how Post Type Discovery reads it.summarycan be replaced and deleted;q=sourcereturnsnameandsummarywhen set. If the content starts with a heading equal toname, that heading is dropped so it isn't shown twice. - Feeds. Only articles have a title: RSS leaves
<title>out (an item needs a title or a description, and every item has a description), JSON Feed leavestitleout, and Atom, which requires<title>, has an empty one. Atom<summary>and JSON Feedsummarycarry the author's summary. Content no longer contains the title, so it isn't repeated. - Pages. The article page has
p-name,p-summary(when set) and the body ase-content. On the homepage and tag pages an article shows its title, summary (or the start of its text) and "Read more", without images. The photos stay in the markup as hiddenu-photovalues so parsers read the same post type there as on the article page. - Crossposting. Articles go to GoToSocial, Bluesky and Threads as title, summary (or the start of the text), link and hashtags, without images, the usual POSSE form for articles. On Bluesky the link card is the article itself. Notes are posted in full as before.
- Editor. Title and Summary fields; a titled note may have no body.
Consequences
- The migration rewrites note files. Back up the database and
data/notes(and.trash) before deploying. Note.titleisNonefor notes. Places that need a name for any post useNote.label(title, else excerpt, else slug): notifications and the Bluesky card.Note.has_titleandNote.body_htmlare gone.- Search indexes the title column; untitled notes are still listed by their first line.
- A crossposted article that is edited is re-posted as a teaser.