docs: 📝 Write article about Versia 0.5

Author: CPlusPatch

bun.lockb

@@ -1,7 +1,4 @@
 <template>
-    <!-- <article
-        class="$style.content mx-auto max-w-3xl prose prose-invert mt-10 prose-code:before:content-none prose-code:after:content-none prose-a:text-orange-500 prose-a:underline"
-        v-html="body"></article> -->
     <article :class="[$style.content, 'prose prose-invert prose-code:before:content-none prose-code:after:content-none']" v-html="body"></article>
 </template>
 
@@ -29,8 +26,12 @@ defineProps<{
     @apply h-6 w-6 flex-none rounded-full bg-gray-800;
 }
 
+.content :global :has(.header-anchor):hover .header-anchor {
+    @apply opacity-100;
+}
+
 .content :global .header-anchor {
-    @apply no-underline absolute w-16 md:w-auto text-right left-[calc(100%-3.75rem)] md:-left-10 text-gray-200
+    @apply no-underline absolute size-6 md:w-auto text-right opacity-0 duration-75 left-[calc(100%-3.75rem)] md:-left-10 text-gray-200
 }
 
 .content :global .header-anchor::before {

components/article/content.vue

@@ -1,12 +1,16 @@
 <template>
-    <nuxt-img :src="image" :width="width" :height="height" format="webp" alt="" :preload="true"
-        class="drop-shadow-2xl w-full rounded bg-zinc-900 ring-1 ring-white/10" />
+    <figure class="space-y-3 w-full">
+        <nuxt-img :src="image" :width="width" :height="height" format="webp" alt="" :preload="true"
+            class="drop-shadow-2xl w-full rounded bg-zinc-900 ring-1 ring-white/10" />
+        <figcaption v-if="caption" class="text-center text-sm text-gray-400">{{ caption }}</figcaption>
+    </figure>
 </template>
 
 <script lang="ts" setup>
 defineProps<{
     image: string;
     width?: number;
     height?: number;
+    caption?: string;
 }>();
 </script>

components/article/image.vue

@@ -1,6 +1,6 @@
 <template>
     <div class="mx-auto max-w-2xl text-center flex items-center justify-center gap-8 flex-col">
-        <h1 v-if="title" class="text-4xl font-bold tracking-tight text-gray-50 sm:text-5xl">
+        <h1 v-if="title" class="text-4xl font-bold tracking-tight text-gray-50 sm:text-5xl font-title">
             {{ title }}
         </h1>
         <div>
@@ -18,7 +18,7 @@ defineProps<{
 }>();
 
 const formatDate = (date?: string) => {
-    return new Intl.DateTimeFormat(undefined, {
+    return new Intl.DateTimeFormat("en-GB", {
         year: "numeric",
         month: "long",
         day: "numeric",

components/article/title.vue

@@ -0,0 +1,40 @@
+<template>
+    <header class="shadow bg-zinc-800">
+        <div class="mx-auto max-w-7xl px-2 sm:px-4 lg:px-8">
+            <div class="relative flex h-16 justify-between">
+                <div class="relative z-10 flex px-2 lg:px-0">
+                    <div class="flex flex-shrink-0 items-center">
+                        <img class="h-8 w-auto" src="https://cdn.versia.pub/branding/icon.svg"
+                            alt="Pink rounded square with three white star icons in the center" />
+                    </div>
+                </div>
+                <div class="relative z-0 flex flex-1 items-center justify-center px-2">
+                    <div class="w-full max-w-xl">
+                        <label for="search" class="sr-only">Search</label>
+                        <div class="relative">
+                            <div class="pointer-events-none absolute inset-y-0 left-0 flex items-center pl-3">
+                                <Icon name="tabler:search" class="size-5 text-gray-300" aria-hidden="true" />
+                            </div>
+                            <input id="search" name="search"
+                                class="block w-full rounded-md border-0 bg-zinc-700 py-1.5 pl-10 pr-3 text-gray-200 ring-1 ring-inset ring-gray-700 placeholder:text-gray-300 focus:ring-2 focus:ring-inset focus:ring-pink-600 sm:text-sm sm:leading-6"
+                                placeholder="Search" type="search" />
+                        </div>
+                    </div>
+                </div>
+            </div>
+            <nav class="hidden sm:flex sm:flex-row flex-col justify-evenly gap-x-8 gap-y-2 py-2" aria-label="Global">
+                <a v-for="item in navigation" :key="item.name" :href="item.href"
+                    :class="['text-gray-100 hover:bg-zinc-700 hover:text-gray-50 inline-flex items-center justify-center rounded py-2 px-3 text-sm font-medium duration-200 w-full']">{{ item.name }}</a>
+            </nav>
+        </div>
+    </header>
+</template>
+
+<script lang="ts" setup>
+const navigation = [
+    { name: "Dashboard", href: "#", current: true },
+    { name: "Team", href: "#", current: false },
+    { name: "Projects", href: "#", current: false },
+    { name: "Calendar", href: "#", current: false },
+];
+</script>

components/navigation/navbar.vue

@@ -46,6 +46,7 @@ export const getPost = async (path: string): Promise<Post | null> => {
             height: header.image_height
                 ? Number(header.image_height)
                 : undefined,
+            credit: header.image_credit,
         },
         title: header.title,
         path,

composables/server/Post.ts

@@ -0,0 +1,199 @@
+---
+title: Versia 0.5 is here!
+created_at: 1737126070000
+description: The latest and greatest version of Versia is here! This release is all about small changes and tweaks to make exchanges more consistent.
+image: /images/vibrant-abstract-purple-pink.jpg
+image_credit: Steve Johnson, Pexels
+image_width: 1280
+image_height: 720
+author: CPlusPatch
+author_image: https://cpluspatch.com/images/avatars/jessew.png
+author_handle: @jessew
+---
+
+Today, on January 17th 2025, I [merged](https://github.com/versia-pub/docs/pull/35) Versia 0.5 into the docs' `main` branch.
+
+This release doesn't bring any major changes, being mostly renames and tweaks to make data exchanges more consistent. The most notable changes are:
+
+- Signature headers have been renamed
+- The nonce in signatures has been replaced by a timestamp
+- Groups are better documented
+    - (and moved to an extension :p)
+- [Versia Links](https://versia.pub/links) are a new feature
+- Some [`Collections`](https://versia.pub/structures/collection) have been swapped for the simpler [`URICollection`](https://versia.pub/structures/collection#uri-collection) format
+- A bunch of new extensions
+
+You can find the full changelog [here](https://versia.pub/changelog).
+
+Let's go over everything in more detail.
+
+## Line endings
+
+For the sake of consistency across OSes and editors, all text fields in Versia now use Unix line endings (`\n`). Most servers already use Unix line endings, but it's good to be explicit about it.
+
+## Renamed headers
+
+The following headers have been renamed:
+
+- `X-Signature` --> `Versia-Signature`
+- `X-Signed-By` --> `Versia-Signed-By`
+
+Why? Well, [RFC 6648](https://tools.ietf.org/html/rfc6648) happened (tldr: the `X-` prefix is deprecated).
+
+## Nonce no more
+
+The `X-Nonce` header in signatures has been replaced by a timestamp. Replay attacks are not really a big concern in the Versia security model, but verifying signature freshness is still a good idea.
+
+### What does this prevent?
+
+Here's an example: Alice accidentally posts her full social security number to a public Versia server. Obviously, she immediately deletes the post, but someone with a malicious instance could replay the note federation request to other servers, essentially bringing it back from the dead.
+
+This is a very contrived example, but it's a good illustration of why we should verify the freshness of signatures.
+
+## Rate limiting
+
+Obeying IETF draft [polli-ratelimit-headers-02](https://www.ietf.org/archive/id/draft-polli-ratelimit-headers-02.html) is now mandatory for all Versia implementations. Implementations running on weaker hardware can sometimes struggle with the load of a large number of requests, so it's important to have a way to throttle federation!
+
+As to the draft itself, it was chosen for its simplicity, so you shouldn't have too much trouble implementing it.
+
+## Groups
+
+Turns out, [`Groups`](https://versia.pub/extensions/groups) were missing a lot of significant information, like how to actually subscribe and receive updates from them. This has been fixed.
+
+The new system introduces a very similar system to the one used for [`Follows`](https://versia.pub/entities/follow), with the following new entities:
+
+- `pub.versia:groups/Subscribe`
+- `pub.versia:groups/Unsubscribe`
+- `pub.versia:groups/SubscribeAccept`
+- `pub.versia:groups/SubscribeReject`
+
+As to federation, the [`Groups`](https://versia.pub/extensions/groups)'s home instance can now federate all notes posted to it while keeping the original author's signature, using the new `pub.versia:groups/Federate` entity. This avoids the need for forwardable signatures, which are a pain to implement.
+
+To top that all off, `Groups` have [been moved to an extension](https://versia.pub/extensions/groups), because they were getting too big for the main spec.
+
+## Versia Links
+
+A common problem on ActivityPub is that you can easily link to a user or a note via its URI, but to interact with it, you need to have your implementation look up that URI in your favourite client. This is a pain. There should be a way to automatically open your favorite client when you click on a link, right?
+
+Well, the issue comes from the fact that there's no way for a client to tell which URIs are Versia URIs (e.g., `https://versia.social/users/jessew`) and which are not (like `https://google.com`). This is where Versia Links come in.
+
+They look like this:
+
+```plaintext
+# Opens a user profile
+web+versia://users/bob.social/alice
+
+# Opens a note
+web+versia://notes/jimbob.com/01902e09-0f8b-72de-8ee3-9afc0cf5eae1
+
+# Opens the composer with a reply to a note
+web+versia://reply/bob.social/01902e09-0f8b-72de-8ee3-9afc0cf5eae1
+```
+
+The `web+` prefix allows Web clients to register support for the `web+versia` scheme, which will open the link in the user's Versia client. This is a simple way to make Versia URIs stand out from the rest.
+
+Versia Links are meant to be used in instances' web UIs, for logged-out users. This replaces the "type your instance's domain" popup that was previously used in [Mastodon](https://joinmastodon.org/), for example.
+
+For more information, check out the [Versia Links spec](https://versia.pub/links).
+
+## Timestamp change
+
+All timestamps now use [RFC 3339](https://tools.ietf.org/html/rfc3339) instead of ISO 8601. [RFC 3339](https://tools.ietf.org/html/rfc3339) can be thought as a more restricted version of ISO 8601, which means that most implementations should already be compatible with it.
+
+```plaintext
+# ISO 8601
+2025-01-17T12:00:00Z
+
+# RFC 3339
+2025-01-17T12:00:00Z
+
+# They're the same!
+# Except now you can't do this horrible thing anymore:
+2025-W03-5T17:04:29/PT2M
+```
+
+[Here's a helpful visualization of the differences between the two](https://ijmacd.github.io/rfc3339-iso8601/).
+
+### Unix timestamps?
+
+Unix timestamps are great for machines, but they're not very human-readable. [RFC 3339](https://tools.ietf.org/html/rfc3339) is a good compromise between the two, being both human-readable and easily machine-readable.
+
+## `$schema` in Entities
+
+Entities can now optionally have a `$schema` field, which allows implementations to include a [JSON Schema](https://json-schema.org/) inside the entity.
+
+This is meant for human use only, and not for either clients or servers to validate the entity. Including the implementation's JSON schema in the entity itself can be useful for debugging and documentation purposes.
+
+## URICollection
+
+Some `Collections` have been swapped for the simpler `URICollection` format. This is a simple list of URIs, which can be used for things like a list of followers, for example.
+
+It is much easier to implement than the full `Collection` format, plus it's also more lightweight.
+
+```json
+{
+    "author": "https://versia.social/users/018ec082-0ae1-761c-b2c5-22275a611771",
+    "first": "https://versia.social/users/018ec082-0ae1-761c-b2c5-22275a611771/followers?page=1",
+    "last": "https://versia.social/users/018ec082-0ae1-761c-b2c5-22275a611771/followers?page=3",
+    "total": 46,
+    "next": "https://versia.social/users/018ec082-0ae1-761c-b2c5-22275a611771/followers?page=2",
+    "previous": null,
+    "items": [
+        "https://versia.social/users/f8b0d4b4-d354-4798-bbc5-c2ba8acabfe3",
+        "https://social.bob.com/u/2B27E62snga763"
+    ]
+}
+```
+
+## Note collections
+
+[Notes](https://versia.pub/entities/note) now have a `collections` field, which regroups `outbox`, `likes`, `replies`, etc.
+
+```json
+{
+    // ...
+    "collections": {
+        "replies": "https://versia.social/objects/01902e09-0f8b-72de-8ee3-9afc0cf5eae1/replies",
+        "quotes": "https://versia.social/objects/01902e09-0f8b-72de-8ee3-9afc0cf5eae1/quotes",
+        "pub.versia:likes/Likes": "https://versia.social/objects/01902e09-0f8b-72de-8ee3-9afc0cf5eae1/likes",
+        "pub.versia:likes/Dislikes": "https://versia.social/objects/01902e09-0f8b-72de-8ee3-9afc0cf5eae1/dislikes",
+        "pub.versia:reactions/Reactions": "https://versia.social/objects/01902e09-0f8b-72de-8ee3-9afc0cf5eae1/reactions"
+    }
+}
+```
+
+This is a simpler structure than in Versia 0.4, where everything was its own top-level field:
+
+```json
+{
+    // ...
+    "replies": "https://versia.social/objects/01902e09-0f8b-72de-8ee3-9afc0cf5eae1/replies",
+    "quotes": "https://versia.social/objects/01902e09-0f8b-72de-8ee3-9afc0cf5eae1/quotes",
+    "extensions": {
+        "pub.versia:likes": {
+            "likes": "https://versia.social/objects/01902e09-0f8b-72de-8ee3-9afc0cf5eae1/likes",
+        }
+    }
+}
+```
+
+## Interaction Controls
+
+The new [Interaction Controls Extension](https://versia.pub/extensions/interaction-controls) allows users to control who can interact with their posts, just like on Bluesky or Twitter. This is great when you're often the target of spam or harassment.
+
+The system has a lot of flexibility while still being simple enough to implement in a weekend or two.
+
+## Smaller stuff
+
+- Usernames can now have uppercase characters. Also, they're now case-insensitive, so `jessew` and `JesseW` are the same user.
+- The [Vanity Extension](https://versia.pub/extensions/vanity) now supports a `timezone` field.
+- Docs have been improved across the board, with [more examples](https://versia.pub/federation/example) and explanations.
+- [`Reports`](https://versia.pub/extensions/reports) are now transient, and the `reason` field was replaced by a `tags` field.
+
+## Conclusion
+
+Is this a large breaking change that will require a lot of work to implement? No, not really. Is it better than the previous version? Yes, definitely.
+
+I hope you have a good time implementing this release. If you have any questions, feel free to contact me, Jesse, [on these socials](https://cpluspatch.com/contact). I'm always glad to help.
+
+Happy hacking!

content/2025/01/17/versia-05.md

@@ -1,11 +1,8 @@
+<script setup lang="ts">
+</script>
+
 <template>
-    <main :class="[$style.content, 'w-full h-full min-h-screen bg-gradient-to-tr from-zinc-900 to-zinc-800']">
+    <main :class="['size-full min-h-screen bg-zinc-900 font-sans']">
         <slot />
     </main>
-</template>
-
-<style lang="css" module>
-.content {
-    font-family: Inter, sans-serif;
-}
-</style>
+</template>

content/test/test-file.md

@@ -94,6 +94,23 @@ export default defineNuxtConfig({
     future: {
         compatibilityVersion: 4,
     },
+    fonts: {
+        defaults: {
+            subsets: ["latin", "latin-ext"],
+        },
+    },
+    security: {
+        headers: {
+            contentSecurityPolicy: {
+                "img-src": [
+                    "'self'",
+                    "data:",
+                    "images.pexels.com",
+                    "cdn.versia.pub",
+                ],
+            },
+        },
+    },
     image: {
         domains: ["images.pexels.com"],
     },