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>
3.9 KiB
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:
- 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.