Files
StarPunk/docs/decisions/ADR-077-article-urls-and-title-slugs.md
T
PhilandClaude Opus 5.5 b7f8e1612c feat: articles at /article/<slug> with slugs from their titles (v2.17.0, ADR-077)
Articles (notes with a title) move from /note/<slug> to /article/<slug>;
the other prefix 301-redirects. New articles take their slug from the
title (mp-slug still wins; notes keep timestamp slugs). A Micropub update
that adds or removes a title answers 201 with the new Location.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 12:27:31 -07:00

2.2 KiB

ADR-077: Article URLs and slugs from titles

Status

Accepted (v2.17.0, 2026-11-12)

Amends ADR-062 (default slugs) for articles and ADR-076 (articles).

Context

ADR-076 (v2.16.0) made a note with a title an article, but articles still got a /note/<timestamp> URL like any other note. An article is not a note, and its URL should say so. ADR-062 chose timestamp slugs because short notes have no good words for a URL and their text may be private; an article has a title written to be read, and that is the usual source of its slug on the IndieWeb.

Decision

  • URLs. Articles live at /article/<slug>, other notes at /note/<slug>. Note.permalink, Note.url, Note.endpoint and utils.post_path / post_url build them; nothing else writes /note/ by hand. Slugs stay unique across both, so a slug still names one post.
  • One URL each, the other redirects. /note/<slug> for an article and /article/<slug> for a note answer 301 to the right one. Adding or removing a title changes the URL, and links made before (webmentions sent, crossposts, bookmarks) keep working. A deleted post is 410 at either.
  • Slug from the title. When a post is created with a title and no mp-slug, the slug is the title made URL-safe (sanitize_slug: accents folded, lowercase, hyphens), cut at a word boundary to 80 characters, -2, -3… if taken, -article if reserved. A title with nothing usable (only emoji, say) falls back to the timestamp slug. Notes keep timestamp slugs.
  • Slugs don't follow later title changes. Editing an article's title, or making a note an article, keeps its slug: a slug is the stable part of the URL.
  • Micropub. Location and q=source give the new URLs. Updates accept either URL. An update that adds or removes a title answers 201 with the new URL in Location, as the Micropub spec requires when a post's URL changes; other updates are still 204.
  • Incoming webmentions to either URL find the post.

Consequences

  • Production had no articles when this shipped, so no published URL changed.
  • A note given a title later keeps its timestamp slug under /article/.
  • Stored URLs (webmention sources, crosspost records) are not rewritten; the redirects cover them.