diff --git a/CHANGELOG.md b/CHANGELOG.md index 9b93498..109b3d3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [2.8.0] - 2026-11-03 + +Microformats2 review: the markup now matches the [microformats2](https://microformats.org/wiki/microformats2) vocabularies, so IndieWeb readers and tools see what the page shows. + +### Fixed + +- Replies to a note weren't marked up as its comments, so readers and threading tools saw none. They are now `u-comment h-cite`s with the replier's h-card (name, link, photo) and the reply's HTML +- Likes, reposts, bookmarks and mentions on a note had no microformats at all. Each is now a `u-like`, `u-repost`, `u-bookmark` or `u-mention` h-cite with its author, including likes past the eight faces shown +- Responses link to and are dated by the original post (its own URL and published time) instead of the address that sent the webmention and when it arrived. New database columns hold these (migration 014) +- Post times had no time zone (and production showed microseconds), so readers could shift them by hours. Times on pages and in Micropub `q=source` are now UTC with a `Z`, matching the Atom feed +- A note starting with a hashtag (`#indieweb is great…`) was treated as a titled article: its text became a heading and the body was empty, and a note starting with a bare `#` line got its slug as a title. Only a Markdown heading (`#` then a space) makes a title now +- A webmention from one of a note's own crossposts (for example your GoToSocial copy, sent back through Bridgy) showed up as a response on the note. It is now ignored +- Micropub and IndieAuth discovery links disappeared from pages when webmentions were turned off +- A new site had no `rel="me"` link to its author, so readers couldn't tell whose site it was; pages now always link `rel="me"` and `rel="author"` to the author's home page +- Finding the author's profile could pick someone else's h-card from their home page. It now follows the [representative h-card](https://microformats.org/wiki/representative-h-card-parsing) rules +- A webmention's author is found by the [authorship algorithm](https://indieweb.org/authorship-spec), from the entry on the source page that actually responds to the note: an author given as a name or link, and the author of a feed the entry is in, now count + +### Added + +- Tag pages and the likes page have a feed URL and author, like the home page +- Note previews have `u-uid` + ## [2.7.2] - 2026-11-03 ### Added diff --git a/docs/design/v2.8.0/2026-11-03-microformats2-review.md b/docs/design/v2.8.0/2026-11-03-microformats2-review.md new file mode 100644 index 0000000..5817337 --- /dev/null +++ b/docs/design/v2.8.0/2026-11-03-microformats2-review.md @@ -0,0 +1,38 @@ +# v2.8.0: Microformats2 review + +Review of StarPunk's published and consumed microformats against +microformats2, h-entry, h-card, h-feed, h-cite, representative h-card +parsing, the authorship spec and Post Type Discovery. Every page type was +rendered, parsed with mf2py and checked with mf2util. + +Posts (h-entry) were largely correct: no implied names, PTD right for +note/article/reply/like/repost/photo, author h-card, u-url/u-uid, +p-category, u-syndication. + +## Fixes + +| # | Problem | Fix | +|---|---|---| +| 1 | Replies were unattached `h-cite` children with a plain-text author | `u-comment h-cite`, `p-author h-card` (u-url on an inner link, u-photo, p-name), `e-content` (`templates/partials/responses.html`) | +| 2 | Likes/reposts/bookmarks/mentions had no mf2 | `u-like` / `u-repost` / `u-bookmark` / `u-mention` h-cites; faces past 8 are `hidden`, not omitted | +| 3 | `dt-*` naive, with microseconds | `iso_utc` filter/helper: RFC 3339 UTC `Z`, no fraction; Micropub `q=source` too | +| 4 | `#hashtag` first line = title; bare `#` = slug title | `split_title` requires an ATX heading (`#{1,6}` + space); templates use `Note.has_title` | +| 5 | Note's own syndicated copy shown as a mention | Worker rejects a source whose url/uid (or URL) is one of the note's `syndications.remote_url` as invalid | +| 6 | Micropub/IndieAuth links gated on WEBMENTION_ENABLED | Only `rel=webmention` is gated | +| 7 | No rel=me on a fresh install | `rel=me` and `rel=author` to `author.url or author.me or ADMIN_ME`, always | +| 8 | Author discovery guessed h-cards | `mf2_utils.representative_hcard` (uid+url, rel=me, single h-card); parsed with the URL after redirects | +| 9 | Webmention entry/author/time | `mf2_utils.responding_entry` (entry whose in-reply-to/like-of/... or content refers to the target), `entry_author` (author property as h-card/URL/name, parent h-feed author, rel=author, representative h-card), `source_post_url` and `source_published` stored (migration 014) | + +Also: tag and likes h-feeds have `u-url` and `p-author`; previews have `u-uid`. + +## Not done + +- Reply-context h-cite does not carry the cached author h-card, name or published time. +- Photo alt falls back to "Image" when a photo-only post has no caption. +- Person tags (`p-category h-card`) are not supported. +- Existing webmentions keep NULL source details until they are re-validated. + +## Tests + +`tests/test_microformats_v280.py`. `tests/test_microformats.py` +`test_no_relme_without_author` became `test_relme_to_admin_me_without_author`. diff --git a/migrations/014_webmention_source_details.sql b/migrations/014_webmention_source_details.sql new file mode 100644 index 0000000..4ea0f1f --- /dev/null +++ b/migrations/014_webmention_source_details.sql @@ -0,0 +1,6 @@ +-- Migration 014: Source details for received webmentions (v2.8.0) +-- The source's own u-url and dt-published, so a response links to and dates +-- the original post rather than the URL that sent it and when it arrived. + +ALTER TABLE webmentions ADD COLUMN source_post_url TEXT; +ALTER TABLE webmentions ADD COLUMN source_published TIMESTAMP; diff --git a/starpunk/__init__.py b/starpunk/__init__.py index 8c8a0d5..b51048e 100644 --- a/starpunk/__init__.py +++ b/starpunk/__init__.py @@ -219,6 +219,10 @@ def create_app(config=None): return {'author': author} + # Template filter - RFC 3339 UTC for dt-* properties (v2.8.0) + from starpunk.utils import iso_utc + app.add_template_filter(iso_utc, 'iso_utc') + # Template filter - URL to color for facepile (v1.6.0) @app.template_filter('url_to_color') def url_to_color_filter(url): @@ -459,5 +463,5 @@ def create_app(config=None): # Package version (Semantic Versioning 2.0.0) # See docs/standards/versioning-strategy.md for details -__version__ = "2.7.2" -__version_info__ = (2, 7, 2) +__version__ = "2.8.0" +__version_info__ = (2, 8, 0) diff --git a/starpunk/author_discovery.py b/starpunk/author_discovery.py index d9f4338..b3e1c64 100644 --- a/starpunk/author_discovery.py +++ b/starpunk/author_discovery.py @@ -82,10 +82,12 @@ def discover_author_profile(me_url: str) -> Optional[Dict]: response.raise_for_status() # Parse microformats from HTML - parsed = mf2py.parse(doc=response.text, url=me_url) + # Relative URLs and the representative h-card use the URL after redirects + page_url = str(response.url) if isinstance(response.url, (str, httpx.URL)) else me_url + parsed = mf2py.parse(doc=response.text, url=page_url) - # Extract h-card (per Q16: first representative h-card) - hcard = _find_representative_hcard(parsed, me_url) + # Representative h-card (v2.8.0: per the parsing spec) + hcard = _find_representative_hcard(parsed, page_url) if not hcard: current_app.logger.warning(f"No h-card found at {me_url}") @@ -132,47 +134,21 @@ def discover_author_profile(me_url: str) -> Optional[Dict]: def _find_representative_hcard(parsed: dict, me_url: str) -> Optional[dict]: """ - Find representative h-card from parsed microformats + Find the representative h-card of the author's page (v2.8.0) - Per Q16: First representative h-card = first h-card with p-name - Per Q18: First h-card with url property matching profile URL + Follows https://microformats.org/wiki/representative-h-card-parsing + (uid+url match, rel=me match, or the only h-card with a matching url). + Other h-cards on the page may be other people, so none is guessed. Args: parsed: Parsed microformats data from mf2py - me_url: Profile URL for matching + me_url: Profile URL (the page that was parsed) Returns: - h-card dict or None if not found + h-card dict or None if the page has no representative h-card """ - items = parsed.get('items', []) - - # First try: h-card with matching URL (most specific) - for item in items: - if 'h-card' in item.get('type', []): - properties = item.get('properties', {}) - urls = properties.get('url', []) - - # Check if any URL matches the profile URL - for url in urls: - if isinstance(url, dict): - url = url.get('value', '') - if _normalize_url(url) == _normalize_url(me_url): - # Found matching h-card - return item - - # Second try: First h-card with p-name (representative h-card) - for item in items: - if 'h-card' in item.get('type', []): - properties = item.get('properties', {}) - if properties.get('name'): - return item - - # Third try: Just use first h-card if any - for item in items: - if 'h-card' in item.get('type', []): - return item - - return None + from starpunk.mf2_utils import representative_hcard + return representative_hcard(parsed, me_url) def _get_property(hcard: dict, prop_name: str) -> Optional[str]: diff --git a/starpunk/mf2_utils.py b/starpunk/mf2_utils.py new file mode 100644 index 0000000..a4f9404 --- /dev/null +++ b/starpunk/mf2_utils.py @@ -0,0 +1,168 @@ +""" +Microformats2 consuming helpers (v2.8.0) + +Shared by Webmention processing and author discovery: +- representative h-card of a page +- the h-entry on a page that responds to a given URL +- the author of an h-entry (authorship algorithm) + +References: + - https://microformats.org/wiki/representative-h-card-parsing + - https://indieweb.org/authorship-spec +""" + +from typing import Iterator, Optional +from urllib.parse import urldefrag, urlparse + +RESPONSE_PROPERTIES = ('in-reply-to', 'like-of', 'repost-of', 'bookmark-of') + + +def normalize_url(url: str) -> str: + """URL for comparison: no fragment, no trailing slash, lowercase scheme/host""" + if not url: + return '' + url = urldefrag(url.strip())[0] + parsed = urlparse(url) + url = parsed._replace(scheme=parsed.scheme.lower(), netloc=parsed.netloc.lower()).geturl() + return url.rstrip('/') + + +def value_of(value) -> Optional[str]: + """Plain value of an mf2 property value (strings, {'value':...}, {'html':...})""" + if isinstance(value, dict): + value = value.get('value') + return value if isinstance(value, str) and value else None + + +def first(item: dict, prop: str) -> Optional[str]: + """First plain value of an item's property""" + for value in item.get('properties', {}).get(prop, []): + result = value_of(value) + if result: + return result + return None + + +def values(item: dict, prop: str) -> list[str]: + """All plain values of an item's property""" + return [v for v in (value_of(x) for x in item.get('properties', {}).get(prop, [])) if v] + + +def walk(items: list) -> Iterator[dict]: + """Every microformat in items, depth first: top level, children, nested properties""" + for item in items: + if not isinstance(item, dict) or 'type' not in item: + continue + yield item + yield from walk(item.get('children', [])) + for prop_values in item.get('properties', {}).values(): + yield from walk([v for v in prop_values if isinstance(v, dict)]) + + +def is_type(item: dict, mf_type: str) -> bool: + return mf_type in item.get('type', []) + + +def representative_hcard(parsed: dict, page_url: str) -> Optional[dict]: + """ + The page's representative h-card, per the parsing spec, in order: + + 1. An h-card whose uid and url both match the page URL + 2. An h-card whose url matches one of the page's rel=me URLs + 3. The only h-card on the page, if its url matches the page URL + + Otherwise the page has none. + """ + page = normalize_url(page_url) + cards = [item for item in walk(parsed.get('items', [])) if is_type(item, 'h-card')] + + for card in cards: + if page in map(normalize_url, values(card, 'uid')) and \ + page in map(normalize_url, values(card, 'url')): + return card + + rel_me = {normalize_url(u) for u in parsed.get('rels', {}).get('me', [])} + for card in cards: + if rel_me & set(map(normalize_url, values(card, 'url'))): + return card + + if len(cards) == 1 and page in map(normalize_url, values(cards[0], 'url')): + return cards[0] + + return None + + +def responding_entry(parsed: dict, target_url: str) -> Optional[dict]: + """ + The h-entry on a page that refers to target_url + + Prefers an entry whose in-reply-to / like-of / repost-of / bookmark-of + is the target, then one whose content links to it, then the first + top-level h-entry. + """ + target = normalize_url(target_url) + entries = [item for item in walk(parsed.get('items', [])) if is_type(item, 'h-entry')] + top = [item for item in parsed.get('items', []) if is_type(item, 'h-entry')] + + if not target: + return top[0] if top else (entries[0] if entries else None) + + for entry in entries: + for prop in RESPONSE_PROPERTIES: + if target in map(normalize_url, values(entry, prop)): + return entry + + for entry in entries: + for content in entry.get('properties', {}).get('content', []): + html = content.get('html', '') if isinstance(content, dict) else str(content) + if target_url in html or target in html: + return entry + + return top[0] if top else (entries[0] if entries else None) + + +def response_type(entry: dict, target_url: str) -> str: + """reply / like / repost / bookmark if the entry is one to target_url, else mention""" + target = normalize_url(target_url) + for prop, kind in zip(RESPONSE_PROPERTIES, ('reply', 'like', 'repost', 'bookmark')): + if target in map(normalize_url, values(entry, prop)): + return kind + return 'mention' + + +def entry_author(parsed: dict, entry: Optional[dict], page_url: str) -> dict: + """ + Author of an h-entry, following the authorship algorithm without fetching + + 1. The entry's author property (an h-card, a URL, or a name) + 2. The author of an h-feed that contains the entry + 3. The page's rel=author link + 4. The page's representative h-card + + Returns: + {'name', 'url', 'photo'}; values may be None + """ + author = None + if entry: + author = (entry.get('properties', {}).get('author') or [None])[0] + if author is None: + for feed in walk(parsed.get('items', [])): + if is_type(feed, 'h-feed') and entry in feed.get('children', []): + author = (feed.get('properties', {}).get('author') or [None])[0] + break + + if author is None: + rel_author = parsed.get('rels', {}).get('author', []) + author = rel_author[0] if rel_author else representative_hcard(parsed, page_url) + + if isinstance(author, dict) and 'type' in author: + return { + 'name': first(author, 'name'), + 'url': first(author, 'url'), + 'photo': first(author, 'photo'), + } + + text = value_of(author) + if text and urlparse(text).scheme in ('http', 'https'): + return {'name': None, 'url': text, 'photo': None} + return {'name': text, 'url': None, 'photo': None} diff --git a/starpunk/micropub.py b/starpunk/micropub.py index 4749c76..19f6390 100644 --- a/starpunk/micropub.py +++ b/starpunk/micropub.py @@ -36,7 +36,7 @@ from starpunk.notes import ( InvalidNoteDataError, NoteNotFoundError, ) from starpunk.indieauth import check_scope -from starpunk.utils import absolute_url_for +from starpunk.utils import absolute_url_for, iso_utc # Custom Exceptions @@ -743,7 +743,7 @@ def note_to_mf2(note, wanted: Optional[list] = None) -> dict: title, content = split_title(note.content) props = { "content": [content], - "published": [note.created_at.isoformat()], + "published": [iso_utc(note.created_at)], "url": [absolute_url_for("public.note", slug=note.slug)], "post-status": ["published" if note.published else "draft"], } diff --git a/starpunk/models.py b/starpunk/models.py index 1b6a74b..a2cd7fb 100644 --- a/starpunk/models.py +++ b/starpunk/models.py @@ -11,6 +11,7 @@ from dataclasses import dataclass, field, replace from datetime import datetime, timedelta from pathlib import Path from typing import Any, Optional +import re import sqlite3 # Third-party imports @@ -40,6 +41,9 @@ MARKDOWN_EXTENSIONS = ["extra", "codehilite", "nl2br", BareUrlExtension()] # Constants - Content limits MAX_TITLE_LENGTH = 200 + +# A Markdown ATX heading: up to 6 '#', whitespace, then text +TITLE_RE = re.compile(r"#{1,6}[ \t]+(\S.*)$") EXCERPT_LENGTH = 200 @@ -47,17 +51,19 @@ def split_title(content: str) -> tuple[Optional[str], str]: """ Split a note's '# Heading' first line (its title, per Q22) off its content + The first line must be a Markdown heading: 1-6 '#' then a space and text. + '#indieweb ...' (a hashtag) or a bare '#' is not a title. This is the one + place that decides whether a note has a title (templates use has_title). + Returns: (title, remaining content); title is None if the note has no heading """ stripped = content.lstrip() - if not stripped.startswith("#"): - return None, content first_line, _, rest = stripped.partition("\n") - title = first_line.lstrip("#").strip() - if not title: + match = TITLE_RE.match(first_line) + if not match: return None, content - return title, rest.strip() + return match.group(1).strip().rstrip("#").strip(), rest.strip() @dataclass(frozen=True) @@ -278,6 +284,14 @@ class Note: return self.html return markdown.markdown(body, extensions=MARKDOWN_EXTENSIONS) + @property + def has_title(self) -> bool: + """True if the note starts with a '# Heading' title (an article)""" + try: + return split_title(self.content)[0] is not None + except (FileNotFoundError, OSError): + return False + @property def title(self) -> str: """ diff --git a/starpunk/utils.py b/starpunk/utils.py index 738fb91..aa18f09 100644 --- a/starpunk/utils.py +++ b/starpunk/utils.py @@ -11,7 +11,7 @@ import hashlib import re import secrets import shutil -from datetime import datetime +from datetime import datetime, timezone from pathlib import Path from typing import Optional @@ -693,3 +693,26 @@ def absolute_url_for(endpoint: str, **values) -> str: from flask import current_app, url_for return current_app.config["SITE_URL"].rstrip("/") + url_for(endpoint, **values) + + +def iso_utc(value) -> str: + """ + Format a timestamp as RFC 3339 UTC for dt-* and Micropub (v2.8.0) + + Stored times are naive UTC. Without an offset, microformats parsers read + them as local time, so this adds 'Z' and drops microseconds (HTML +