From be47ce61b217f6df1eb91337c98a155bdb249538 Mon Sep 17 00:00:00 2001
From: Gabriel Kaszewski <gabrielkaszewski@gmail.com>
Date: Fri, 29 May 2026 02:14:24 +0000
Subject: [PATCH] wiki: add Pinned Posts page

---
 Pinned-Posts.md | 45 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)
 create mode 100644 Pinned-Posts.md

diff --git a/Pinned-Posts.md b/Pinned-Posts.md
new file mode 100644
index 0000000..c768a09
--- /dev/null
+++ b/Pinned-Posts.md
@@ -0,0 +1,45 @@
+# Pinned Posts
+
+k-ap serves `GET /users/{id}/featured` automatically as an `OrderedCollection` of pinned post URLs. By default the collection is empty.
+
+---
+
+## Enable pinned posts
+
+Override `get_featured_objects` in your `ApContentReader`:
+
+```rust
+impl ApContentReader for MyDb {
+    async fn get_featured_objects(&self, user_id: Uuid) -> anyhow::Result<Vec<Url>> {
+        let urls = self.fetch_pinned_post_urls(user_id).await?;
+        Ok(urls)
+    }
+
+    // ... other required methods
+}
+```
+
+---
+
+## Wire up the URL in ApUser
+
+Set `featured_url` to the endpoint URL so it appears in actor JSON:
+
+```rust
+ApUser {
+    featured_url: Some(
+        format!("https://example.com/users/{}/featured", user.id).parse()?
+    ),
+    // ... other fields
+}
+```
+
+k-ap includes `featured_url` as the `featured` field in actor JSON. Clients like Mastodon follow this link from the actor's `featured` field to display pinned posts on a profile.
+
+---
+
+## How it works
+
+`GET /users/{id}/featured` is registered by `service.router()`. When a request arrives, k-ap calls `ApContentReader::get_featured_objects(user_id)` and returns an `OrderedCollection` with the returned URLs as `orderedItems`.
+
+The collection is always a flat list of URLs — it does not include the full object JSON. Remote clients fetch each URL individually if they need the content.
\ No newline at end of file