Files
StarPunk/docs/design/v2.16.0/2026-11-11-article-titles-and-summaries.md
T
PhilandClaude Opus 5.5 ccb9f6dce2 fix: keep inline images in Micropub articles (v2.16.0)
- Content sent as both html and text is stored as the HTML; the text is
  usually a plain fallback, so images, links and headings were lost.
- Images embedded from other sites are copied into the media library
  (SSRF-checked fetcher, best effort, max 20) and the text points at the
  copies, on create and on content replace.
- HTML content is sanitized as is instead of going through Markdown, which
  added stray <br>s and empty paragraphs.

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

4.4 KiB

v2.16.0: Article titles and summaries

Implements ADR-076. Prompted by a review of how StarPunk handles IndieWeb articles: titles were repeated in feeds, every feed item had a made-up title, Micropub summary was dropped, and any note starting with a heading became an article.

What changed

Area Change
Storage Migration 023 adds notes.title and notes.summary; create_note/update_note take title and summary (UNCHANGED sentinel on update; None/"" clears)
Migration data step migrations.DATA_MIGRATIONS["023_note_titles.sql"] = _move_note_titles; run_migrations(..., data_dir=) gets DATA_PATH from init_db. Moves # Heading first lines (via split_title) into title, finds trashed files with utils.find_trashed_file (shared with undelete_note), updates content_hash, empties notes_fts. Files are restored if the migration fails
Model Note.title/summary fields; Note.label for places that need some name; has_title, body_html and the first-line title property removed
Micropub name → title, summary → summary (only with content), summary updatable, q=source returns both; a heading repeating name is dropped (drop_title_heading)
Feeds Titles only for articles (RSS none, JSON none, Atom empty); Atom/JSON summaries
Templates Article page: p-name, p-summary, e-content without the title. Previews: title, summary or excerpt, "Read more", no images (hidden u-photo data kept for Post Type Discovery)
Crossposting compose_text posts articles as title + article_teaser (summary, or 200 characters of plain text) + link + hashtags; no images for articles; Bluesky card is the article
Editor Title and Summary fields on new/edit; content not required when titled
Search FTS indexes title; untitled notes still use their first line
MCP create_note/update_note take summary; note summaries include it

Fixes found along the way

  • Hashtag lines. Python-Markdown made #indieweb is fun an <h1>; CommonMark needs a space after #. markdown_ext.HashtagLineExtension escapes the first # of a line where #s run straight into text, after fenced code and raw HTML are set aside. It is used for pages and feeds (MARKDOWN_EXTENSIONS) and crosspost plain text (syndication._note_soup), so the hashtag also reaches Bluesky as a tag. Search's first-line label keeps hashtags too.

  • Plain-text excerpt. Note.excerpt only stripped # marks, so previews showed **bold** and [link](url). It is now syndication.plain_text of the content, cut to 200 characters with …; article_teaser is the summary or this excerpt.

  • Inline images in Micropub articles. (1) extract_content prefers html over text and marks it content_format = 'html': clients send text as a plain fallback, so images, links and headings were lost. (2) localize_inline_images copies images from other sites (Markdown ![]() or <img>) into the media library through the SSRF-checked fetcher used for photo, on create and on content replace, and rewrites their URLs; failures keep the original URL, at most 20 per post. Images stay inline (not u-photo), so the post remains an article. (3) Note.html sanitizes HTML content with nh3 directly instead of passing it through Markdown.

Choices made with the owner

  • Title column rather than an editor-only field, as the most standards-compliant option.
  • Atom entries for notes keep an empty <title> (required by RFC 4287).
  • Homepage and tag pages: articles show title and summary without images.
  • Crossposts: articles as title + summary + link, no images.

Tests

  • tests/test_articles.py (new): feeds per format, article page mf2, homepage and tag-page previews, admin create/edit/clear, title-only article.
  • tests/test_migration_023.py (new): titles moved (including trashed notes), hashtag first line untouched, hashes and FTS, runs once, files restored on failure, schema-only without data_dir.
  • Updated for the new behaviour: test_feed.py, test_feeds_{atom,json,rss}.py, test_routes_feed.py, test_models.py, test_microformats.py, test_microformats_v280.py, test_micropub.py, test_micropub_v240.py (plus new summary and empty-body tests), test_syndication.py and test_syndication_bluesky.py (article crossposts).
  • Locally: the 35 affected test files, 872+ tests, pass. CI runs the full suite on the tag.