mirror of
https://github.com/versia-pub/docs.git
synced 2025-12-06 14:28:20 +01:00
68 lines
2.7 KiB
Plaintext
68 lines
2.7 KiB
Plaintext
export const metadata = {
|
|
title: 'Versia Links',
|
|
description:
|
|
'How Versia Links work and how they are used in the Versia Protocol.',
|
|
}
|
|
|
|
# Versia Links
|
|
|
|
Versia Links are a way to reference entities in the Versia Protocol, in a way that can be handled by browsers and applications. They function the same way as `mailto:` links, but for Versia entities.
|
|
|
|
## Syntax
|
|
|
|
<Row>
|
|
<Col>
|
|
<Properties name="Versia Link">
|
|
<Property name="scheme" type="string" required={true}>
|
|
Must be `web+versia://` so that browsers and applications can recognize it.
|
|
|
|
An IANA registration for the `versia://` scheme will be requested in the future.
|
|
</Property>
|
|
<Property name="action" type="string" required={true}>
|
|
Action to take on the entity. Can have multiple slashes as a way to segment the action.
|
|
Links that reference instance-specific content (like Entities) **must** reference a Instance.
|
|
|
|
Possible actions:
|
|
|
|
- `users/:instance/:id`: Open a user profile.
|
|
- `notes/:instance/:id`: Open a note.
|
|
- `groups/:instance/:id`: Open a group.
|
|
- `reply/:instance/:id`: Open the composer to reply to a note.
|
|
- `quote/:instance/:id`: Open the composer to quote a note.
|
|
- `share/:instance/:id`: Share a note.
|
|
- `compose/:text`: Compose a new note. Text passed at the end will be added in the note compose field. Used for "Share with Versia" buttons on websites.
|
|
</Property>
|
|
<Property name="instance" type="Domain" typeLink="/api/basics#domain" required={false}>
|
|
Instance hosting the referenced content.
|
|
</Property>
|
|
</Properties>
|
|
</Col>
|
|
|
|
<Col sticky>
|
|
``` {{ title: "Viewing a user profile" }}
|
|
web+versia://users/bob.social/alice
|
|
```
|
|
|
|
``` {{ title: "Viewing a note" }}
|
|
web+versia://notes/jimbob.com/01902e09-0f8b-72de-8ee3-9afc0cf5eae1
|
|
```
|
|
|
|
``` {{ title: "Replying to a note" }}
|
|
web+versia://reply/bob.social/01902e09-0f8b-72de-8ee3-9afc0cf5eae1
|
|
```
|
|
</Col>
|
|
</Row>
|
|
|
|
## Handling
|
|
|
|
Versia clients **should** register themselves as handlers for the `web+versia://` scheme in the user's operating system. When a Versia Link is clicked, the client should open the entity in the client's interface.
|
|
|
|
The default web client ("frontend") on a Versia instance **should** also display Versia links for logged-out users on:
|
|
- Profiles
|
|
- Notes
|
|
- Groups
|
|
|
|
This **could** be used for easier following of users from remote instances.
|
|
|
|
Clients **should** ask users to confirm any action that is not a simple view action, such as replying to a note or sharing a note.
|