Files
StarPunk/docs/design/v2.3.3/2026-10-31-micropub-title-and-source-url.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

2.4 KiB

v2.3.3: Micropub titles, q=source URL, single title display

Superseded in v2.16.0 by ADR-076: titles are stored in notes.title, not as a # Heading in the content, and split_title is used only to move old headings and drop a heading that repeats name.

Found while building tuipub, a terminal Micropub client, against StarPunk.

Problems

  1. Micropub name dropped. handle_create called extract_title() and threw the result away. StarPunk has no title column: Note.title is derived from the content's first line, and a # Heading first line marks a titled note (Q22). So a name sent by a client never showed up.
  2. q=source URL wrong. It built {SITE_URL}notes/{slug}, but the route is /note/<slug>, so the URL was a 404.
  3. q=source name wrong. It returned note.title for every note. For untitled notes that is just the first line of the content, so clients saw a name they never sent.
  4. Title shown twice. note.html renders the title as <h1 class="p-name"> and then the whole content, which includes the # Heading again. Home-page previews did the same with the excerpt.

Decisions

  • Store name as a # {name} first line (micropub.add_title_heading) rather than adding a title column. This matches how titled notes already work everywhere (pages, feeds, search, admin editor), and needs no migration. If the content already starts with that exact heading, it isn't added twice.
  • models.split_title() is the single definition of "title heading": the first non-blank line starting with # (the same rule as the templates' has_explicit_title). q=source uses it to return name + content the way they were posted.
  • Note.body_html renders the content without the title heading; note.html uses it. Note.excerpt also leaves the title out. Note.html is unchanged, so feeds and syndication behave as before (feed items carry a separate title anyway).
  • extract_title() no longer derives a fallback title from content: that value was never used.

Tests

  • tests/test_micropub.py: name stored as heading, no duplicate heading, q=source url equals the Location permalink, name only for titled notes, round trip.
  • tests/test_models.py: split_title, body_html, excerpt without title.
  • Checked end to end with tuipub against a local dev server: titled post → page shows the title once, q=source returns name, content and a working url.