wholetrans/docs-mastodon
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update anchors, line breaks, tootctl options (#745)

Browse source 
* update anchors

* remove extraneous anchors

* fix line breaks

* wrap tootctl tokens in code blocks

* change anchors to hugo format

* fix mistaken search-and-replace

* fix mistaken search-and-replace
This commit is contained in:
trwnh 2020-01-12 07:11:56 -06:00 • committed by Eugen Rochko
parent 32d4dd5803
commit 7ceae9fe36
72 changed files with 1219 additions and 1223 deletions
Download patch file Download diff file Expand all files Collapse all files

40
content/en/spec/activitypub.md
View file

@ -1,8 +1,6 @@
---
title: ActivityPub
description: >-
A decentralized social networking protocol based upon the ActivityStreams 2.0
data format and JSON-LD.
description: A decentralized social networking protocol based upon the ActivityStreams 2.0 data format and JSON-LD.
menu:
docs:
weight: 10
@ -13,7 +11,7 @@ menu:
Sample payloads will be added at a future date.
{{< /hint >}}
## Status federation <a id="status"></a>
## Status federation {#status}
{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/lib/activitypub/activity.rb" caption="app/lib/activitypub/activity.rb" >}}
@ -43,7 +41,7 @@ Some other Object types are converted as best as possible. The transformer uses
* Video
* Event
## Profile federation <a id="profile"></a>
## Profile federation {#profile}
### Supported activities for profiles
@ -75,7 +73,7 @@ Some other Object types are converted as best as possible. The transformer uses
| attachment | Used for profile fields. See [Profile metadata](activitypub.md#profile-metadata) and [Identity proofs](activitypub.md#identityproof). |
| alsoKnownAs | Required for Move activity. |
## HTML sanitization <a id="sanitization"></a>
## HTML sanitization {#sanitization}
{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/lib/sanitize_config.rb" caption="app/lib/sanitize\_config.rb" >}}
@ -91,11 +89,11 @@ Some other Object types are converted as best as possible. The transformer uses
* ellipsis
* invisible
## JSON-LD Namespacing <a id="namespaces"></a>
## JSON-LD Namespacing {#namespaces}
{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/lib/activitypub/adapter.rb" caption="app/lib/activitypub/adapter.rb" >}}
### Mastodon extensions \(`toot:`\) <a id="toot"></a>
### Mastodon extensions \(`toot:`\) {#toot}
Contains definitions for Mastodon features.
@ -107,7 +105,7 @@ Contains definitions for Mastodon features.
* toot:discoverable
* toot:votersCount
### ActivityStreams extensions \(`as:`\) <a id="as"></a>
### ActivityStreams extensions \(`as:`\) {#as}
Contains ActivityStreams extended properties that have been proposed but not officially adopted yet.
@ -117,7 +115,7 @@ Contains ActivityStreams extended properties that have been proposed but not off
* as:movedTo
* as:sensitive
### W3ID Security Vocabulary \(`sec:`\) <a id="sec"></a>
### W3ID Security Vocabulary \(`sec:`\) {#sec}
Contains properties used for HTTPS Signatures and Linked Data Signatures. Also used for identity proofs. See [Security](security.md) for more information.
@ -136,7 +134,7 @@ Contains a collection of terms from various namespaces, used for Linked Data Sig
* sec:signature
* sec:signatureValue
### schema.org extensions \(`schema:`\) <a id="schema"></a>
### schema.org extensions \(`schema:`\) {#schema}
Contains properties used for profile metadata.
@ -145,7 +143,7 @@ Contains properties used for profile metadata.
## Extensions
### Public key
### Public key {#publicKey}
Public keys are used for HTTPS Signatures and Linked Data Signatures. This is implemented using an extra property `publicKey` on actor objects. See [Security](security.md) for more information. Example:
@ -165,7 +163,7 @@ Public keys are used for HTTPS Signatures and Linked Data Signatures. This is im
}
```
### Featured collection <a id="featured"></a>
### Featured collection {#featured}
What is known in Mastodon as “pinned toots”, or statuses that are always featured at the top of people’s profiles, is implemented using an extra property `featured` on the actor object that points to a `Collection` of objects. Example:
@ -188,7 +186,7 @@ What is known in Mastodon as “pinned toots”, or statuses that are always fea
}
```
### Custom emojis <a id="emoji"></a>
### Custom emojis {#emoji}
Mastodon supports arbitrary emojis, that is, small images uploaded by admins and invokable via shortcodes. For this, an `Emoji` type is used. These emojis are listed in the `tag` property just like `Mention` and `Hashtag` objects, since they are entities that affect how the text is rendered. Example:
@ -220,7 +218,7 @@ Mastodon supports arbitrary emojis, that is, small images uploaded by admins and
}
```
### Focal points <a id="focalpoint"></a>
### Focal points {#focalPoint}
Mastodon supports setting a focal point on uploaded images, so that wherever that image is displayed, the focal point stays in view. This is implemented using an extra property `focalPoint` on `Image` objects. The property is simply an array of two floating points between -1.0 and 1.0, with 0,0 being the center of the image, the first value being x \(-1.0 is the left edge, +1.0 is the right edge\) and the second value being y \(-1.0 is the bottom edge, +1.0 is the top edge\). See [Focal points](../methods/statuses/media.md#focal-points) for more information. Example:
@ -254,7 +252,7 @@ Mastodon supports setting a focal point on uploaded images, so that wherever tha
}
```
### Blurhash
### Blurhash {#blurhash}
Mastodon generates colorful preview thumbnails for attachments. This is implemented using an extra property `blurhash` on `Image` objects. The property is a string generated by the [BlurHash algorithm](https://blurha.sh). Example:
@ -282,7 +280,7 @@ Mastodon generates colorful preview thumbnails for attachments. This is implemen
}
```
### Profile metadata
### Profile metadata {#PropertyValue}
Mastodon supports arbitrary profile fields containing name-value pairs. This is implemented using the `attachment` property on actor objects, with objects in the array having a type of `PropertyValue` and a `value` property, both from the schema.org namespace. Example:
@ -301,18 +299,18 @@ Mastodon supports arbitrary profile fields containing name-value pairs. This is
{
"type": "PropertyValue",
"name": "Patreon",
"value": "<a href=\"https://www.patreon.com/mastodon\" rel=\"me nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://www.</span><span class=\"\">patreon.com/mastodon</span><span class=\"invisible\"></span></a>"
"value": "<a href=\"https://www.patreon.com/mastodon\" rel=\"me nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://www.</span><span class=\"\">patreon.com/mastodon</span><span class=\"invisible\"></span}"
},
{
"type": "PropertyValue",
"name": "Homepage",
"value": "<a href=\"https://zeonfederated.com\" rel=\"me nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">zeonfederated.com</span><span class=\"invisible\"></span></a>"
"value": "<a href=\"https://zeonfederated.com\" rel=\"me nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">zeonfederated.com</span><span class=\"invisible\"></span}"
}
]
}
```
### Identity proofs <a id="identityproof"></a>
### Identity proofs {#IdentityProof}
Mastodon supports integration with identity providers to prove that a profile is linked to a certain identity. This is implemented using the `attachment` property on actor objects, with objects in the array having a type of `IdentityProof` from the Mastodon namespace. The object also includes `signatureAlgorithm` and `signatureValue` from the W3ID Security Vocabulary namespace. Example:
@ -339,7 +337,7 @@ Mastodon supports integration with identity providers to prove that a profile is
}
```
### Discoverability flag <a id="discoverable"></a>
### Discoverability flag {#discoverable}
Mastodon allows users to opt-in or opt-out of discoverability features like the profile directory. This flag may also be used as an indicator of the user's preferences toward being included in external discovery services, such as search engines or other indexing tools. If you are implementing such a tool, it is recommended that you respect this property if it is present. This is implemented using an extra property `discoverable` on objects. Example:

48
content/en/spec/microformats.md
View file

@ -7,92 +7,92 @@ menu:
parent: spec
---
## What are microformats?
## What are microformats? {#intro}
[Microformats 2.0](https://microformats.io/) is a standard used to embed metadata directly within an HTML document. Rather than needing to use an API for read-only purposes, a web page can simply be parsed for certain CSS classes in order to extract information that you have already fetched simply by viewing the page, rather than having to separately request that same information from an API. The use of microformats classes allows for semantic parsing of data within a given web page, and can be used to generate feeds, cards, or representations of that data.
## Microformats classes
## Microformats classes {#classes}
All microformats classes use a prefix. The prefix indicates the type of the element, independent of hierarchy. These are the microformats classes as used in Mastodon's codebase.
### Root elements \(`h-*`\)
### Root elements \(`h-*`\) {#h}
#### `h-feed`
#### `h-feed` {#h-feed}
Represents a stream of entries. Attached to a profile's toots. Also attached to the parent thread within detailed status views.
#### `h-entry`
#### `h-entry` {#h-entry}
Represents episodic or date stamped online content. Attached to a status.
#### `h-cite`
#### `h-cite` {#h-cite}
Represents a reference to another online publication. Attached to a boost. Also attached to other statuses in the thread within detailed status views.
#### `h-card`
#### `h-card` {#h-card}
Represents a person or organization. Attached to the container of display name, username, and avatar. Also attached to mentions.
### Plain-text properties \(`p-*`\)
### Plain-text properties \(`p-*`\) {#p}
#### `p-author`
#### `p-author` {#p-author}
Within `h-entry` or `h-cite`, represents the author of the entry, and is attached to the container of display name, username, and avatar.
#### `p-name`
#### `p-name` {#p-name}
Within `h-feed`, represents the title of the feed. Attached to `data` element with `value` attribute.
Within `h-entry` or `h-cite`, represents the title of the entry. Unused in Mastodon.
Within `h-card`, represents the plain-text name of a person or organization. Attached to display name.
#### `p-in-reply-to`
#### `p-in-reply-to` {#p-in-reply-to}
Within `h-entry` of a detailed status, represents the status that is the direct parent.
#### `p-repost-of`
#### `p-repost-of` {#p-repost-of}
Within h-entry of a detailed status, represents a post that is a reblog and also a direct parent. Currently unused, since reblogs cannot be replied to.
#### `p-comment`
#### `p-comment` {#p-comment}
Within `h-entry` of a detailed status, represents statuses that are direct children.
### URL properties \(`u-*`\)
### URL properties \(`u-*`\) {#u}
#### `u-photo`
#### `u-photo` {#u-photo}
Within `h-card`, represents the profile picture. Attached to the avatar image.
#### `u-uid`
#### `u-uid` {#u-uid}
Within `h-entry` or `h-cite`, represents a universally unique identifier. Attached to timestamp link.
#### `u-url`
#### `u-url` {#u-url}
Within `h-entry` or `h-cite`, represents the status permalink. Attached to timestamp link.
Within `h-card`, represents the profile permalink. Attached to display name link.
### Datetime properties \(`dt-*`\)
### Datetime properties \(`dt-*`\) {#dt}
#### `dt-published`
#### `dt-published` {#dt-published}
Within `h-entry` or `h-cite`, represents the date and time at which the status was published. Attached to `data` element with `value` attribute.
### Element tree \(`e-*`\)
### Element tree \(`e-*`\) {#e}
#### `e-content`
#### `e-content` {#e-content}
Within `h-entry` or `h-cite`, represents the content of the status. Attached to status content.
## Additional classes
## Additional classes {#mastodon}
These elements are attached by Mastodon for parsing metadata, but are not technically part of the Microformats vocabulary.
#### `mention`
#### `mention` {#mention}
Indicates that the link should be opened in-app with the associated mention data from the API.
#### `hashtag`
#### `hashtag` {#hashtag}
Indicates that the link should be opened in-app with the associated hashtag data from the API.

14
content/en/spec/oauth.md
View file

@ -1,15 +1,13 @@
---
title: OAuth
description: >-
An open standard for token-based authentication and authorization on the
Internet
description: An open standard for token-based authentication and authorization on the Internet
menu:
docs:
weight: 50
parent: spec
---
## What is OAuth?
## What is OAuth? {#intro}
The Mastodon API has many methods that require authentication from a client or authorization from a user. This is accomplished with OAuth 2.0, an authorization framework described in [RFC 6749](https://tools.ietf.org/html/rfc6749) that allows third-party applications to obtain limited access to an HTTP service on behalf of a resource owner, through the use of a standardized authorization flow that generates a client access token to be used with HTTP requests.
@ -21,7 +19,7 @@ Mastodon supports the following OAuth 2 flows:
To obtain an OAuth token for a Mastodon website, make sure that you allow your users to specify the domain they want to connect to before login. Use that domain to [acquire a client id/secret](../methods/apps/#create-an-application) and then [proceed with normal OAuth 2]({{< relref "../methods/apps/oauth.md" >}}).
## OAuth 2 endpoints implemented <a id="oauth-2-endpoints"></a>
## OAuth 2 endpoints implemented {#implementation}
The following descriptions are taken from the [Doorkeeper documentation](https://github.com/doorkeeper-gem/doorkeeper/wiki/API-endpoint-descriptions-and-examples). Mastodon uses Doorkeeper to implement OAuth 2. For more information on how to use these endpoints, see the [API documentation for OAuth.]({{< relref "../methods/apps/oauth.md" >}})
@ -31,15 +29,15 @@ The following descriptions are taken from the [Doorkeeper documentation](https:/
Displays an authorization form to the user. If approved, it will create and return an authorization code, then redirect to the desired `redirect_uri`, or show the authorization code if `urn:ietf:wg:oauth:2.0:oob` was requested.
### [POST /oauth/token](../methods/apps/oauth.md#obtain-a-token) <a id="post-oauth-token"></a>
### [POST /oauth/token](../methods/apps/oauth.md#obtain-a-token) {#post-oauth-token}
Obtain an access token. This corresponds to the token endpoint, section 3.2 of the OAuth 2 RFC.
### [POST /oauth/revoke](../methods/apps/oauth.md#revoke-token) <a id="post-oauth-revoke"></a>
### [POST /oauth/revoke](../methods/apps/oauth.md#revoke-token) {#post-oauth-revoke}
Post here with client credentials to revoke an access token. This corresponds to the token endpoint, using the OAuth 2.0 Token Revocation RFC \(RFC 7009\).
## Common gotchas <a id="common-gotchas"></a>
## Common gotchas {#gotchas}
* When registering an application using Mastodon's REST API, there is a `scopes` parameter. When interfacing with OAuth endpoints, you must use the `scope` parameter instead, and this parameter's value must be a subset of the `scopes` registered with the app. You cannot include anything that wasn't in the original set.
* When registering an application using Mastodon's REST API, there is a `redirect_uris` parameter. When interfacing with OAuth endpoints, you must use the `redirect_uri` parameter instead, and this parameter's value must be one of the `redirect_uris` registered with the app.

12
content/en/spec/security.md
View file

@ -7,7 +7,7 @@ menu:
parent: spec
---
## HTTP Signatures
## HTTP Signatures {#http}
{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/lib/request.rb" caption="app/lib/request.rb" >}}
@ -40,7 +40,7 @@ The `keyId` should correspond to the actor and the key being used to generate th
See also: [https://blog.joinmastodon.org/2018/07/how-to-make-friends-and-verify-requests/](https://blog.joinmastodon.org/2018/07/how-to-make-friends-and-verify-requests/)
### Creating HTTP signatures
### Creating HTTP signatures {#http-sign}
To create an HTTP signature, you will have to define which headers are being hashed and signed. For example, consider the following request being sent out:
@ -73,7 +73,7 @@ Signature: keyId="https://my-example.com/actor#main-key",headers="(request-targe
This request is functionally equivalent to saying that `https://my-example.com/actor` is requesting `https://mastodon.example/users/username/inbox` and is proving that they sent this request by signing `(request-target)`, `Host:`, and `Date:` with their public key linked at `keyId`, resulting in the provided `signature`.
### Verifying HTTP signatures
### Verifying HTTP signatures {#http-verify}
{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/controllers/concerns/signature_verification.rb" caption="app/controllers/concerns/signature\_verification.rb" >}}
@ -95,7 +95,7 @@ Mastodon verifies the signature using the following algorithm:
* SHA256 hash the signature string and compare to the Base64-decoded `signature` as decrypted by `publicKey[publicKeyPem]`.
* Use the Date: header to check that the signed request was made within the past 12 hours.
## Linked Data Signatures
## Linked Data Signatures {#ld}
{{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/lib/activitypub/linked_data_signature.rb" caption="app/lib/activitypub/linked\_data\_signature.rb" >}}
@ -104,7 +104,7 @@ Mastodon verifies the signature using the following algorithm:
* When running a [self-destruct](../admin/tootctl.md#tootctl-self-destruct) sequence to send Delete activities to all known peers, the payload will use LD Signatures because HTTP Signatures will not be available. Receiving servers will process the signature by validating it against the locally cached actor key, since the HTTP server will no longer be hosting old actor information.
* When accepting activities from a relay. Public activities can optionally be sent to a relay with LD Signatures, and any server subscribing to a relay does not have to manually refetch the activity from the origin. This prevents having potentially infinite servers attempt to load the status from your instance.
### Creating LD signatures
### Creating LD signatures {#ld-sign}
To create a signature, Mastodon uses the keypair attached to an actor at `https://mastodon.example/users/username#main-key`. It then creates an SHA256 hash of the document, signs it with the keypair, and Base64-strict-encodes the resulting output to derive a `signatureValue`. The following hash is merged into the JSON-LD document:
@ -121,7 +121,7 @@ To create a signature, Mastodon uses the keypair attached to an actor at `https:
Mastodon's current implementation of LD Signatures is somewhat outdated due to a change in the JSON-LD @context between the drafting stage and finalization stage of the specification. Mastodon expects a `type` of `RsaSignature2017` while the current specification instead defines `RsaSignature2018` via the namespace `https://w3id.org/security/v2`.
{{< /hint >}}
### Verifying LD signatures
### Verifying LD signatures {#ld-verify}
To verify a signature, Mastodon uses the following algorithm:

4
content/en/spec/webfinger.md
View file

@ -7,7 +7,7 @@ menu:
parent: spec
---
## What is WebFinger, and why is it used?
## What is WebFinger, and why is it used? {#intro}
On Mastodon, user profiles can be hosted either locally on the same website as yours, or remotely on a completely different website. The same username may be used on a different domain. Therefore, a Mastodon user's full mention consists of both the username and the domain, in the form `@username@domain`. In practical terms, `@user@example.com` is not the same as `@user@example.org`. If the domain is not included, Mastodon will try to find a local user named `@username`. However, in order to deliver to someone over ActivityPub, the `@username@domain` mention is not enough -- **mentions must be translated to an HTTPS URI first**, so that the remote actor's inbox and outbox can be found.
@ -17,7 +17,7 @@ Enter WebFinger. WebFinger as described in [RFC 7033](https://tools.ietf.org/htm
**Because Mastodon heavily relies on mentions for addressing other profiles, WebFinger is required for fully interoperating with Mastodon.** Users can generally load profiles by searching for the direct HTTPS URI if they know it, or for the `username@domain` address, but Mastodon's internal logic depends almost completely on `acct`: URIs or `username@domain` representations. Searching for any objects or profiles from an ActivityPub implementation without WebFinger will fail because the author cannot be converted to a user in the local database.
{{< /hint >}}
## Sample WebFinger flow
## Sample WebFinger flow {#example}
Suppose we want to lookup the user `@Gargron` hosted on the `mastodon.social` website.