Files
StarPunk/docs/decisions/ADR-076-note-title-and-summary-columns.md
T
PhilandClaude Opus 5.5 b7f8e1612c feat: articles at /article/<slug> with slugs from their titles (v2.17.0, ADR-077)
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>
2026-11-12 12:27:31 -07:00

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:

  1. Feeds repeated an article's title: the item title, then the same heading rendered at the top of the content.
  2. 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.
  3. Micropub summary was used only when content was missing; sent together with content, it was dropped.
  4. Any note that happened to start with a heading became an article, and its q=source changed from what the client sent. Micropub and mf2 treat name and content as separate properties.

Decision

  • Columns. notes.title and notes.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 into title, rewrites the file and updates content_hash, then empties notes_fts so 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 → summary when content is also sent. A summary on its own is still stored as the content, which is how Post Type Discovery reads it. summary can be replaced and deleted; q=source returns name and summary when set. If the content starts with a heading equal to name, 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 leaves title out, and Atom, which requires <title>, has an empty one. Atom <summary> and JSON Feed summary carry 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 as e-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 hidden u-photo values 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.title is None for notes. Places that need a name for any post use Note.label (title, else excerpt, else slug): notifications and the Bluesky card. Note.has_title and Note.body_html are 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.