From b321eb2c1dbec849216e8cccb38b74547f3b7ac2 Mon Sep 17 00:00:00 2001 From: Jesse Wierzbinski Date: Wed, 24 Jul 2024 15:31:45 +0200 Subject: [PATCH] docs: :memo: Document the Note entity --- app/entities/notes/page.mdx | 160 +++++++++++++++++++++++++++++ components/ExperimentalWarning.tsx | 3 +- components/Navigation.tsx | 5 +- 3 files changed, 165 insertions(+), 3 deletions(-) create mode 100644 app/entities/notes/page.mdx diff --git a/app/entities/notes/page.mdx b/app/entities/notes/page.mdx new file mode 100644 index 0000000..2eee397 --- /dev/null +++ b/app/entities/notes/page.mdx @@ -0,0 +1,160 @@ +export const metadata = { + title: 'Notes', + description: 'Definition of the Note entity', +} + +# Notes + +Notes represent a piece of content on a Lysand instance. They can be posted by [Users](/entities/users) and are displayed in a user's feed. Notes can contain text, images, and other media. {{ className: 'lead' }} + + + Notes are not just limited to microblogging. They can be used for any kind of content, such as forum posts, blog posts, image posts, video posts, audio posts, and even messaging. + + +## Entity Definition + + + + + + Media attachments to the note. May be any format. + + + URI of the `User` considered the author of the note. + + + Category of the note. Useful for clients to render notes differently depending on their intended purpose. + + ```typescript + type Category = + | "microblog" // Like Twitter, Mastodon + | "forum" // Like Reddit + | "blog" // Like WordPress, Medium + | "image" // Like Instagram + | "video" // Like YouTube, PeerTube + | "audio" // Like SoundCloud, Spotify + | "messaging"; // Like Discord, Element (Matrix), Signal + ``` + + + The content of the note. Must be text format (`text/html`, `text/markdown`, etc). Must not be remote. + + + Device used to post the note. Useful for functionality such as Twitter's "posted via" feature. + + ```typescript + type Device = { + name: string; + version?: string; + url?: string; + } + ``` + + + URI of a [Group](/groups) that the note is only visible in, or one of the following strings: + - `public`: The note is visible to anyone. + - `followers`: The note is visible only to the author's followers. + + If not provided, the note is only visible to the author and those mentioned in the note. + + + Whether the note contains "sensitive content". This can be used with `subject` as a "content warning" feature. + + + URIs of [Users](/entities/users) that should be notified of the note. Similar to Twitter's `@` mentions. The note may also contain mentions in the content, however only the mentions in this field should trigger notifications. + + + Previews for any links in the publication. This is to avoid the [stampeding mastodon problem](https://github.com/mastodon/mastodon/issues/23662) where a link preview is fetched by every server that sees the publication, creating an accidental DDOS attack. + + ```typescript + type LinkPreview = { + link: string; + title: string; + description?: string; + image?: string; + icon?: string; + } + ``` + + + Servers should make sure not to trust the previews, as they could be faked by malicious remote servers. This is not a very good attack vector, but it is still possible to redirect users to malicious links. + + + + URI of the note that this note is quoting, if any. Quoting is similar to replying, but does not notify the author of the quoted note. Inspired by Twitter's "quote tweet" feature. + + + URI of the note that this note is a reply to, if any. + + + A subject for the note. Useful for clients to display a "content warning" or "spoiler" feature, such as on Mastodon. Must be a plaintext string (`text/plain`). + + + + + + ```jsonc {{ 'title': 'Example Note' }} + { + "id": "01902e09-0f8b-72de-8ee3-9afc0cf5eae1", + "type": "Note", + "uri": "https://social.lysand.org/objects/01902e09-0f8b-72de-8ee3-9afc0cf5eae1", + "created_at": "2024-06-19T01:07:44.139Z", + "attachments": [ // [!code focus:100] + { + "image/png": { + "content": "https://cdn.lysand.org/29e810bf4707fef373d886af322089d5db300fce66e4e073efc26827f10825f6/image.webp", + "remote": true, + "blurhash": "UPBy,E-qM{M_~qx]RjRP^+xuRjRjx[kWjajF", + "description": "", + "height": 960, + "size": 221275, + "hash": { + "sha256": "967b8e86d8708c6283814f450efcbd3be94d3d24ca9a7ab435b2ff8b51dcbc21" + }, + "width": 639 + } + }, + { + "image/png": { + "content": "https://cdn.lysand.org/4f87598d377441e78f3c8cfa7bd7d19d61a7470bfe0abcbee6eb1de87279fb3b/image.webp", + "remote": true, + "blurhash": "U14xf0_N~XRp?btkxaIn$--r%4=~NFniNFad", + "description": "", + "height": 1051, + "size": 122577, + "hash": { + "sha256": "fe4ef842e04495dac7c148b440d83f366b948c4a18557457109ac951d5c46eaf" + }, + "width": 926 + } + } + ], + "author": "https://social.lysand.org/users/018eb863-753f-76ff-83d6-fd590de7740a", + "category": "microblog", + "content": { + "text/html": { + "content": "

In the next lysand-fe update: account settings, finally!

" + }, + "text/plain": { + "content": "In the next lysand-fe update: account settings, finally!" + } + }, + "device": { + "name": "Megalodon for Android", + "version": "1.3.89", + "url": "https://sk22.github.io/megalodon" + }, + "extensions": { + "org.lysand:custom_emojis": { + "emojis": [] + } + }, + "group": "public", + "is_sensitive": false, + "mentions": [], + "subject": "Lysand development" + } + ``` + + + \ No newline at end of file diff --git a/components/ExperimentalWarning.tsx b/components/ExperimentalWarning.tsx index 2ec1bda..08bddc2 100644 --- a/components/ExperimentalWarning.tsx +++ b/components/ExperimentalWarning.tsx @@ -13,8 +13,7 @@ export const ExperimentalWarning: FC = () => ( > - This is a testing site used for development, not a finished - page. + This site is experimental and under active development.

diff --git a/components/Navigation.tsx b/components/Navigation.tsx index 82fac8a..4a02641 100644 --- a/components/Navigation.tsx +++ b/components/Navigation.tsx @@ -260,7 +260,10 @@ export const navigation: NavGroup[] = [ }, { title: "Entities", - links: [{ title: "Users", href: "/entities/users" }], + links: [ + { title: "Users", href: "/entities/users" }, + { title: "Notes", href: "/entities/notes" }, + ], }, ];