Files
StarPunk/docs/decisions/ADR-076-note-title-and-summary-columns.md
T
PhilandClaude Opus 5.5 978c13358b feat: article titles and summaries stored apart from the text (v2.16.0, ADR-076)
Articles as the IndieWeb defines them: a name separate from the content.

- Migration 023 adds notes.title and notes.summary. A one-time Python data
  step (migrations.DATA_MIGRATIONS) moves each note's '# Heading' first line
  into title, rewrites the file and hash, empties FTS for a rebuild, and puts
  files back if the migration fails. Trashed notes included.
- Micropub: name -> title, summary stored when sent with content, summary
  updatable, q=source returns both. MCP tools take a summary.
- Feeds: titles only for articles (RSS/JSON none, Atom empty); Atom and
  JSON Feed summaries; the title is no longer repeated in the content.
- Pages: p-name/p-summary on the article page. Homepage and tag pages show
  articles as title, summary and "Read more" without images (hidden u-photo
  keeps the post type for parsers).
- Crossposts: articles go out as title, summary, link and hashtags, no
  images; the Bluesky card is the article. Notes unchanged.
- Editor: Title and Summary fields; an article may have no body.
- Fix: a line starting with a hashtag ('#indieweb ...') was rendered as a
  heading and crossposted without its '#' (HashtagLineExtension).
- Fix: excerpts showed raw Markdown; they are plain text now.

Back up the database and the data folder before deploying: the migration
rewrites note files.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 17:05:38 -07:00

3.9 KiB

ADR-076: Article titles and summaries stored apart from the text

Status

Accepted (v2.16.0, 2026-11-11)

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.