From 391bdb9db332ef475af4088cd375d7403383592a Mon Sep 17 00:00:00 2001 From: Phil Date: Sat, 31 Oct 2026 19:34:23 -0600 Subject: [PATCH] fix: Micropub titles, q=source URL, single title display (v2.3.3) Micropub `name` was dropped; store it as the note's '# Heading' first line, which is how StarPunk titles work. q=source returned /notes/ (a 404) and a name for every note; it now returns the real permalink and name only for titled notes, without the heading in content. Titled notes no longer show their title twice (Note.body_html, excerpt). Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 9 +++ ...026-10-31-micropub-title-and-source-url.md | 23 +++++++ starpunk/__init__.py | 2 +- starpunk/micropub.py | 59 ++++++++---------- starpunk/models.py | 36 ++++++++++- templates/note.html | 2 +- tests/test_micropub.py | 60 +++++++++++++++++++ tests/test_models.py | 39 +++++++++++- 8 files changed, 191 insertions(+), 39 deletions(-) create mode 100644 docs/design/v2.3.3/2026-10-31-micropub-title-and-source-url.md diff --git a/CHANGELOG.md b/CHANGELOG.md index d3372fa..ad2ea3a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [2.3.3] - 2026-10-31 + +### Fixed + +- Micropub `name` was ignored, so titles sent by Micropub clients never appeared. It is now stored as the note's `# Heading` first line, which is how StarPunk titles work +- Micropub `q=source` returned `/notes/` links (a 404); it now returns the real permalink `/note/` +- Micropub `q=source` reported every note's first line as its `name`; it now returns `name` only for titled notes, with the heading left out of `content`, matching what was posted +- Titled notes showed their title twice: as the page heading and again at the top of the body (and of the home-page summary) + ## [2.3.2] - 2026-10-31 ### Changed diff --git a/docs/design/v2.3.3/2026-10-31-micropub-title-and-source-url.md b/docs/design/v2.3.3/2026-10-31-micropub-title-and-source-url.md new file mode 100644 index 0000000..51b97a8 --- /dev/null +++ b/docs/design/v2.3.3/2026-10-31-micropub-title-and-source-url.md @@ -0,0 +1,23 @@ +# v2.3.3: Micropub titles, q=source URL, single title display + +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/`, 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 `

` 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. diff --git a/starpunk/__init__.py b/starpunk/__init__.py index 65bb855..87d60b9 100644 --- a/starpunk/__init__.py +++ b/starpunk/__init__.py @@ -464,5 +464,5 @@ def create_app(config=None): # Package version (Semantic Versioning 2.0.0) # See docs/standards/versioning-strategy.md for details -__version__ = "2.3.2" +__version__ = "2.3.3" __version_info__ = (2, 1, 0) diff --git a/starpunk/micropub.py b/starpunk/micropub.py index d4eeb86..e0927e2 100644 --- a/starpunk/micropub.py +++ b/starpunk/micropub.py @@ -7,7 +7,7 @@ interface for creating posts via external clients. Functions: normalize_properties: Convert form/JSON data to Micropub properties format extract_content: Get content from Micropub properties - extract_title: Get or generate title from Micropub properties + extract_title: Get the explicit title (name) from Micropub properties extract_tags: Get category tags from Micropub properties handle_create: Process Micropub create action handle_query: Process Micropub query endpoints @@ -28,6 +28,7 @@ from typing import Optional from flask import Request, current_app, jsonify +from starpunk.models import split_title from starpunk.notes import create_note, get_note, InvalidNoteDataError, NoteNotFoundError from starpunk.indieauth import check_scope from starpunk.utils import absolute_url_for @@ -189,38 +190,31 @@ def extract_content(properties: dict) -> str: def extract_title(properties: dict) -> Optional[str]: """ - Extract or generate title from Micropub properties + Extract the explicit title (Micropub 'name' property) - Per ADR-029 mapping rules: - 1. Use 'name' property if provided - 2. If no name, extract from content (first line, max 50 chars) + StarPunk has no title field: a note's title is a '# Heading' first line + (see Note.title), so the caller stores the name as that heading. Args: properties: Normalized Micropub properties dict Returns: - Title string or None + Title on a single line, or None if no name was sent """ - # Try explicit name property first - name = properties.get("name", [""])[0] - if name: - return name.strip() + name = (properties.get("name") or [""])[0] + if not isinstance(name, str): + return None + return " ".join(name.split()) or None - # Generate from content (first line, max 50 chars) - content_list = properties.get("content", []) - if content_list: - content = content_list[0] - # Handle structured content - if isinstance(content, dict): - content = content.get("text") or content.get("html", "") - if content: - first_line = content.split("\n")[0].strip() - if len(first_line) > 50: - return first_line[:50] + "..." - return first_line - - return None +def add_title_heading(content: str, title: Optional[str]) -> str: + """Prefix content with '# title' unless it already starts with that heading""" + if not title: + return content + first_line = content.lstrip().split("\n", 1)[0] + if first_line.startswith("#") and first_line.lstrip("#").strip() == title: + return content + return f"# {title}\n\n{content}" def extract_tags(properties: dict) -> list[str]: @@ -428,7 +422,7 @@ def handle_create(data: dict, token_info: dict): # Create note using existing CRUD try: note = create_note( - content=content, + content=add_title_heading(content, title), published=True, # Micropub posts are published by default created_at=published_date, custom_slug=custom_slug, @@ -520,21 +514,20 @@ def handle_query(args: dict, token_info: dict): current_app.logger.error(f"Failed to get note source: {e}") return error_response("server_error", "Failed to retrieve post") - # Convert note to Micropub Microformats2 format - # Note: SITE_URL is normalized to include trailing slash (for IndieAuth spec compliance) - site_url = current_app.config.get("SITE_URL", "http://localhost:5000") + # Convert note to Micropub Microformats2 format. A '# Heading' first + # line is the title, returned as name (mirrors how create stores it). + title, content = split_title(note.content) mf2 = { "type": ["h-entry"], "properties": { - "content": [note.content], + "content": [content], "published": [note.created_at.isoformat()], - "url": [f"{site_url}notes/{note.slug}"], + "url": [absolute_url_for("public.note", slug=note.slug)], }, } - # Add optional properties - if note.title: - mf2["properties"]["name"] = [note.title] + if title: + mf2["properties"]["name"] = [title] # Add tags if present (v1.3.0) if note.tags: diff --git a/starpunk/models.py b/starpunk/models.py index 1f49fe7..20a9ac7 100644 --- a/starpunk/models.py +++ b/starpunk/models.py @@ -43,6 +43,23 @@ MAX_TITLE_LENGTH = 200 EXCERPT_LENGTH = 200 +def split_title(content: str) -> tuple[Optional[str], str]: + """ + Split a note's '# Heading' first line (its title, per Q22) off its content + + 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: + return None, content + return title, rest.strip() + + @dataclass(frozen=True) class Note: """ @@ -244,6 +261,19 @@ class Note: return self._cached_html + @property + def body_html(self) -> str: + """ + Rendered HTML without the title heading + + Pages show a titled note's title as their own heading, so the body + leaves it out to avoid showing it twice. Untitled notes: same as html. + """ + title, body = split_title(self.content) + if title is None: + return self.html + return markdown.markdown(body, extensions=MARKDOWN_EXTENSIONS) + @property def title(self) -> str: """ @@ -311,10 +341,10 @@ class Note: 'This is my note content. It has some interesting points...' """ try: - # Get content - content = self.content + # Leave out the title; previews show it separately + _, content = split_title(self.content) - # Remove markdown heading syntax from first line + # Remove markdown heading syntax lines = content.split("\n") cleaned_lines = [] for line in lines: diff --git a/templates/note.html b/templates/note.html index 7612d31..51cf9ae 100644 --- a/templates/note.html +++ b/templates/note.html @@ -44,7 +44,7 @@ {# e-content: note content BELOW media (per ADR-057) #}
- {{ note.html|safe }} + {{ note.body_html|safe }}