From 5ebc8ad4183fee82c46aa9a8cd70260f08ed84ca Mon Sep 17 00:00:00 2001 From: Moritz Date: Mon, 10 Aug 2020 23:01:50 +0200 Subject: [PATCH] Replace and fix broken links with hugos relref (#801) As discussed in #764 there are quite a lot of outdated links in the mastodon documentation. In basically all cases this was resolved by simply wrapping the old plain markdown link in hugos `relref` function[^0]. While quite a lot of links on the `/zh-cn/` also appear to be broken, these can not be fixed by just wrapping them in `relref`[^0]. Those are all links to `/spec/` subpages which are just not translated to `/zh-cn/` version. Therefore, `/zh-cn/spec/` has been excluded from the automated checking as described in the next section. The page has been checked using the linkchecker[^1] utility. One process is running `hugo serve` in order to see all changes in real time and notice errors directly in your browser. In a separate command prompt the command `linkchecker http://localhost:1313 --ignore-url=/zh-cn/spec` is being fired up. Note the `--ignore-url=/zh-cn/spe` to exclude the just not existing parts of the page as mentioned in the previous paragraph. There still is some ToDo on the table since quite a lot of the anchors appear to not be set or at least differ from previous versions. One example: on `/client/authorized/` is a link to `/client/token/#creating-our-application` while the id of referenced heading is `app`. These changes **do not** fix those Issues as it would require way more time. [^0]: https://gohugo.io/functions/relref/ [^1]: https://github.com/linkchecker/linkchecker Close #764 --- content/en/client/authorized.md | 18 ++++++++--------- content/en/client/guidelines.md | 4 ++-- content/en/client/public.md | 30 ++++++++++++++-------------- content/en/client/token.md | 10 +++++----- content/en/entities/account.md | 8 ++++---- content/en/entities/activity.md | 2 +- content/en/entities/admin-report.md | 8 ++++---- content/en/entities/application.md | 6 +++--- content/en/entities/attachment.md | 2 +- content/en/entities/context.md | 6 +++--- content/en/entities/conversation.md | 4 ++-- content/en/entities/emoji.md | 2 +- content/en/entities/field.md | 4 ++-- content/en/entities/history.md | 2 +- content/en/entities/identityproof.md | 4 ++-- content/en/entities/instance.md | 2 +- content/en/entities/mention.md | 4 ++-- content/en/entities/notification.md | 4 ++-- content/en/entities/poll.md | 2 +- content/en/entities/preferences.md | 12 +++++------ content/en/entities/relationship.md | 2 +- content/en/entities/results.md | 6 +++--- content/en/entities/source.md | 6 +++--- content/en/entities/status.md | 2 +- content/en/entities/tag.md | 4 ++-- content/en/entities/token.md | 6 +++--- content/en/methods/statuses/media.md | 8 ++++++-- content/en/spec/activitypub.md | 14 ++++++------- content/en/spec/oauth.md | 8 ++++---- content/en/spec/security.md | 4 ++-- 30 files changed, 99 insertions(+), 95 deletions(-) diff --git a/content/en/client/authorized.md b/content/en/client/authorized.md index 27210d32..7c3b4f3c 100644 --- a/content/en/client/authorized.md +++ b/content/en/client/authorized.md @@ -11,7 +11,7 @@ menu: When we registered our app and when we will authorize our user, we need to define what exactly our generated token will have permission to do. This is done through the use of OAuth scopes. Each API method has an associated scope, and can only be called if the token being used for authorization has been generated with the corresponding scope. -Scopes must be a subset. When we created our app, we specified `read write follow push` -- we could simply request all available scopes by specifying `read write follow push`, but it is a better idea to only request what your app will actually need through granular scopes. See [OAuth Scopes](../api/oauth-scopes.md) for a full list of scopes. Each API method's documentation will also specify the OAuth access level and scope required to call it. +Scopes must be a subset. When we created our app, we specified `read write follow push` -- we could simply request all available scopes by specifying `read write follow push`, but it is a better idea to only request what your app will actually need through granular scopes. See [OAuth Scopes]({{< relref "../api/oauth-scopes.md" >}}) for a full list of scopes. Each API method's documentation will also specify the OAuth access level and scope required to call it. ## **Example authorization code flow** {#flow} @@ -19,11 +19,11 @@ This is similar to the authentication flow from before, but this time, we need t ### Client ID and secret {#client} -First, if you have not already registered a client application, then see [Creating our application](token.md#creating-our-application) on the previous page or go directly to [POST /api/v1/apps](../methods/apps/#create-an-application) for the full documentation of that method. We will need the `client_id` and `client_secret` for our application. +First, if you have not already registered a client application, then see [Creating our application]({{< relref "token.md#creating-our-application" >}}) on the previous page or go directly to [POST /api/v1/apps]({{< relref "../methods/apps.md#create-an-application" >}}) for the full documentation of that method. We will need the `client_id` and `client_secret` for our application. ### Authorize the user {#login} -To authorize a user, request [GET /oauth/authorize](../methods/apps/oauth.md#authorize-a-user) in a browser with the following query parameters: +To authorize a user, request [GET /oauth/authorize]({{< relref "../methods/apps/oauth.md#authorize-a-user" >}}) in a browser with the following query parameters: ```bash https://mastodon.example/oauth/authorize @@ -36,12 +36,12 @@ https://mastodon.example/oauth/authorize Note the following: * `client_id` and `client_secret` were obtained when registering our application. -* `scope` must be a subset of our registered app's registered scopes. It is a good idea to only request what you need. See [OAuth Scopes](../api/oauth-scopes.md) for more information. +* `scope` must be a subset of our registered app's registered scopes. It is a good idea to only request what you need. See [OAuth Scopes]({{< relref "../api/oauth-scopes.md" >}}) for more information. * `redirect_uri` is one of the URIs we registered with our app. We are still using "out of band" for this example, which means we will have to manually copy and paste the resulting code, but if you registered your application with a URI that you control, then the code will be returned as a query parameter `code` and can be logged by your request handler. See the response section of the API method documentation for more information on this. ### Obtain the token {#token} -Now that we have an authorization `code`, let's obtain an access token that will authenticate our requests as the authorized user. To do so, use [POST /oauth/token](../methods/apps/oauth.md#obtain-a-token) like before, but pass the authorization code we just obtained: +Now that we have an authorization `code`, let's obtain an access token that will authenticate our requests as the authorized user. To do so, use [POST /oauth/token]({{< relref "../methods/apps/oauth.md#obtain-a-token" >}}) like before, but pass the authorization code we just obtained: ```bash curl -X POST \ @@ -59,9 +59,9 @@ Note the following: * `client_id` and `client_secret` were provided in the response text when you registered your application. * `redirect_uri` must be one of the URIs defined when registering the application. * We are requesting a `grant_type` of `authorization_code`, which still defaults to giving us the `read` scope. However, while authorizing our user, we requested a certain `scope` -- pass the exact same value here. -* The `code` can only be used once. If you need to obtain a new token, you will need to have the user authorize again by repeating the above [Authorize the user](authorized.md#authorize-the-user) step. +* The `code` can only be used once. If you need to obtain a new token, you will need to have the user authorize again by repeating the above [Authorize the user]({{< relref "authorized.md#authorize-the-user" >}}) step. -The response of this method is a [Token]({{< relref "../entities/token.md" >}}) entity. We will need the `access_token` value. Once you have the access token, save it in your local cache. To use it in requests, add the HTTP header `Authorization: Bearer ...` to any API call that requires OAuth \(i.e., one that is not publicly accessible\). Let's verify that our obtained credentials are working by calling [GET /api/v1/accounts/verify\_credentials](../methods/accounts/#verify-account-credentials): +The response of this method is a [Token]({{< relref "../entities/token.md" >}}) entity. We will need the `access_token` value. Once you have the access token, save it in your local cache. To use it in requests, add the HTTP header `Authorization: Bearer ...` to any API call that requires OAuth \(i.e., one that is not publicly accessible\). Let's verify that our obtained credentials are working by calling [GET /api/v1/accounts/verify\_credentials]({{< relref "../methods/accounts/#verify-account-credentials" >}}): ```bash curl \ @@ -77,7 +77,7 @@ With our OAuth token for the authorized user, we can now perform any action as t ### Publish and delete statuses {#statuses} -* See [POST /api/v1/statuses](../methods/statuses/#publish-new-status) for how to create statuses. +* See [POST /api/v1/statuses]({{< relref "../methods/statuses/#publish-new-status" >}}) for how to create statuses. * See [/api/v1/media]({{< relref "../methods/statuses/media.md" >}}) for creating media attachments. * See [/api/v1/scheduled\_statuses]({{< relref "../methods/statuses/scheduled_statuses.md" >}}) for managing scheduled statuses. @@ -87,7 +87,7 @@ With our OAuth token for the authorized user, we can now perform any action as t * See [/api/v1/markers]({{< relref "../methods/timelines/markers.md" >}}) for saving and loading positions in timelines. * See [/api/v1/statuses]({{< relref "../methods/statuses/" >}}) for performing actions on statuses. * See [/api/v1/polls]({{< relref "../methods/statuses/polls.md" >}}) for viewing and voting on polls. -* See [/api/v1/lists]({{< relref "../methods/timelines/lists.md" >}}) for obtaining list IDs to use with [GET /api/v1/timelines/list/:list\_id](../methods/timelines/#list-timeline). +* See [/api/v1/lists]({{< relref "../methods/timelines/lists.md" >}}) for obtaining list IDs to use with [GET /api/v1/timelines/list/:list\_id]({{< relref "../methods/timelines/#list-timeline" >}}). * See [/api/v1/conversations]({{< relref "../methods/timelines/conversations.md" >}}) for obtaining direct conversations. * See [/api/v1/favourites]({{< relref "../methods/accounts/favourites.md" >}}) for listing favourites. * See [/api/v1/bookmarks]({{< relref "../methods/accounts/bookmarks.md" >}}) for listing bookmarks. diff --git a/content/en/client/guidelines.md b/content/en/client/guidelines.md index 90c93f97..84e06c38 100644 --- a/content/en/client/guidelines.md +++ b/content/en/client/guidelines.md @@ -26,11 +26,11 @@ With that said, because IDs are string representations of numbers, they can stil ## Formatting {#formatting} -Plain text is not available for content from remote servers, and plain text syntax rules may vary wildly between Mastodon and other fediverse applications. For certain attributes, such as the content of statuses, **Mastodon provides sanitized HTML**. You may expect these tags to appear in the content: `

`, `
`, ``, ``. See [HTML Sanitization](../spec/activitypub.md#html-sanitization) for more details. +Plain text is not available for content from remote servers, and plain text syntax rules may vary wildly between Mastodon and other fediverse applications. For certain attributes, such as the content of statuses, **Mastodon provides sanitized HTML**. You may expect these tags to appear in the content: `

`, `
`, ``, ``. See [HTML Sanitization]({{< relref "../spec/activitypub.md#html-sanitization" >}}) for more details. ### Mentions, hashtags, and custom emoji {#tags} -Mentions and hashtags are `` tags. Custom emoji remain in their plain text shortcode form. To give those entities their semantic meaning and add special handling, such as opening a mentioned profile within your app instead of as a web page, metadata is included with the [Status]({{< relref "../entities/status.md" >}}), which can be matched to a particular tag. See [Status > Rendering attributes](../entities/status.md#rendering-attributes) for more information. +Mentions and hashtags are `` tags. Custom emoji remain in their plain text shortcode form. To give those entities their semantic meaning and add special handling, such as opening a mentioned profile within your app instead of as a web page, metadata is included with the [Status]({{< relref "../entities/status.md" >}}), which can be matched to a particular tag. See [Status > Rendering attributes]({{< relref "../entities/status.md#rendering-attributes" >}}) for more information. ### Link shortening {#links} diff --git a/content/en/client/public.md b/content/en/client/public.md index fd950b50..e2794bba 100644 --- a/content/en/client/public.md +++ b/content/en/client/public.md @@ -19,7 +19,7 @@ Examples will be written using the fictional Mastodon website, mastodon.example, Let's take a look at one of the most basic use cases for public data from Mastodon -- the public timelines. -We can try to request [GET /api/v1/timelines/public](../methods/timelines/#public-timeline) like so: +We can try to request [GET /api/v1/timelines/public]({{< relref "../../methods/timelines.md" >}}) like so: ```bash curl https://mastodon.example/api/v1/timelines/public @@ -52,7 +52,7 @@ Our response should be more manageable this time. We can parse or beautify this ] ``` -We can do similarly for hashtags by calling [GET /api/v1/timelines/tag/:hashtag](../methods/timelines/#hashtag-timeline) -- here, the colon means that this part of the endpoint is a path parameter. In the case of :hashtag, this means we use the hashtag's name \(and once again, a limit of 2\): +We can do similarly for hashtags by calling [GET /api/v1/timelines/tag/:hashtag]({{< relref "../../methods/timelines.md#hashtag-timeline" >}}) -- here, the colon means that this part of the endpoint is a path parameter. In the case of :hashtag, this means we use the hashtag's name \(and once again, a limit of 2\): ```bash curl https://mastodon.example/api/v1/timelines/tag/cats?limit=2 @@ -82,13 +82,13 @@ Parsing JSON and using it in your program is outside of the scope of this tutori Now that we are familiar with how to make requests and how to handle responses, you can experiment with more public data. The following methods may be of interest: -* Once you know an account's id, you can use [GET /api/v1/accounts/:id](../methods/accounts/#account) to view the [Account]({{< relref "../entities/account.md" >}}) entity. - * To view public statuses posted by that account, you can use [GET /api/v1/accounts/:id/statuses](../methods/accounts/#statuses) and parse the resulting array of [Status]({{< relref "../entities/status.md" >}}) entities. -* Once you know a status's id, you can use [GET /api/v1/statuses/:id](../methods/statuses/#view-specific-status) to view the Status entity. - * You can also use [GET /api/v1/statuses/:id/reblogged\_by](../methods/statuses/#boosted-by) to view who boosted that status, - * or [GET /api/v1/statuses/:id/favourited\_by](../methods/statuses/#favourited-by) to view who favourited that status. - * Requesting [GET /api/v1/statuses/:id/context](../methods/statuses/#parent-and-child-statuses) will show you the ancestors and descendants of that status in the tree that is the conversational thread. - * If the status has a poll attached, you can use [GET /api/v1/polls/:id](../methods/statuses/polls.md#view-a-poll) to view the poll separately. +* Once you know an account's id, you can use [GET /api/v1/accounts/:id]({{< relref "../../methods/accounts.md" >}}) to view the [Account]({{< relref "../entities/account.md" >}}) entity. + * To view public statuses posted by that account, you can use [GET /api/v1/accounts/:id/statuses]({{< relref "../../methods/statuses.md" >}}) and parse the resulting array of [Status]({{< relref "../entities/status.md" >}}) entities. +* Once you know a status's id, you can use [GET /api/v1/statuses/:id]({{< relref "../../methods/statuses.md#view-specific-status" >}}) to view the Status entity. + * You can also use [GET /api/v1/statuses/:id/reblogged\_by]({{< relref "../../methods/statuses.md#boosted-by" >}}) to view who boosted that status, + * or [GET /api/v1/statuses/:id/favourited\_by]({{< relref "../../methods/statuses.md#favourited-by" >}}) to view who favourited that status. + * Requesting [GET /api/v1/statuses/:id/context]({{< relref "../../methods/statuses.md#parent-and-child-statuses" >}}) will show you the ancestors and descendants of that status in the tree that is the conversational thread. + * If the status has a poll attached, you can use [GET /api/v1/polls/:id]({{< relref "../../methods/statuses/polls.md" >}}) to view the poll separately. IDs of accounts and statuses are local to the Mastodon website's database and will differ for each Mastodon website. @@ -96,12 +96,12 @@ IDs of accounts and statuses are local to the Mastodon website's database and wi One last thing you can do with anonymous requests is to view information about the Mastodon website. -* View general information with [GET /api/v1/instance](../methods/instance/#fetch-instance), - * view its peers with [GET /api/v1/instance/peers](../methods/instance/#list-of-connected-domains) or - * its weekly activity with [GET /api/v1/instance/activity](../methods/instance/#weekly-activity), or to - * list all custom emoji available with [GET /api/v1/custom\_emojis](../methods/instance/custom_emojis.md#custom-emoji). -* See [GET /api/v1/directory](../methods/instance/directory.md#view-profile-directory) for a directory of all available profiles. -* See [GET /api/v1/trends](../methods/instance/trends.md#trending-tags) for currently trending hashtags. +* View general information with [GET /api/v1/instance]({{< relref "../../methods/instance.md#fetch-instance" >}}), + * view its peers with [GET /api/v1/instance/peers]({{< relref "../../methods/instance.md#list-of-connected-domains" >}}) or + * its weekly activity with [GET /api/v1/instance/activity]({{< relref "../../methods/instance.md#weekly-activity" >}}), or to + * list all custom emoji available with [GET /api/v1/custom\_emojis]({{< relref "../../methods/instance/custom_emojis.md#custom-emoji" >}}). +* See [GET /api/v1/directory]({{< relref "../../methods/instance/directory.md#view-profile-directory" >}}) for a directory of all available profiles. +* See [GET /api/v1/trends]({{< relref "../../methods/instance/trends.md#trending-tags" >}}) for currently trending hashtags. {{< hint style="info" >}} For a practical example of what you can do with just instance data, see [emojos.in](https://emojos.in/), which lets you preview all custom emoji at a given instance. diff --git a/content/en/client/token.md b/content/en/client/token.md index f26a8946..b8206a2e 100644 --- a/content/en/client/token.md +++ b/content/en/client/token.md @@ -29,13 +29,13 @@ curl -X POST \ In the above example, we specify the client name and website, which will be shown on statuses if applicable. But more importantly, note the following two parameters: * `redirect_uris` has been set to the "out of band" token generation, which means that any generated tokens will have to be copied and pasted manually. The parameter is called `redirect_uris` because it is possible to define more than one redirect URI, but when generating the token, we will need to provide a URI that is included within this list. -* `scopes` allow us to define what permissions we can request later. However, the requested scope later can be a subset of these registered scopes. See [OAuth Scopes](../api/oauth-scopes.md) for more information. +* `scopes` allow us to define what permissions we can request later. However, the requested scope later can be a subset of these registered scopes. See [OAuth Scopes]({{< relref "../api/oauth-scopes.md" >}}) for more information. -We should see an Application entity returned, but for now we only care about client\_id and client\_secret. These values will be used to generate access tokens, so they should be cached for later use. See [POST /api/v1/apps](../methods/apps/#create-an-application) for more details on registering applications. +We should see an Application entity returned, but for now we only care about client\_id and client\_secret. These values will be used to generate access tokens, so they should be cached for later use. See [POST /api/v1/apps]({{< relref "../../methods/apps.md#create-an-application" >}}) for more details on registering applications. ## Example authentication code flow {#flow} -Now that we have an application, let's obtain an access token that will authenticate our requests as that client application. To do so, use [POST /oauth/token](../methods/apps/oauth.md#obtain-a-token) like so: +Now that we have an application, let's obtain an access token that will authenticate our requests as that client application. To do so, use [POST /oauth/token]({{< relref "../../methods/apps/oauth.md#obtain-a-token" >}}) like so: ```bash curl -X POST \ @@ -52,7 +52,7 @@ Note the following: * `redirect_uri` must be one of the URIs defined when registering the application. * We are requesting a `grant_type` of `client_credentials`, which defaults to giving us the `read` scope. -The response of this method is a [Token]({{< relref "../entities/token.md" >}}) entity. We will need the `access_token` value. Once you have the access token, save it in your local cache. To use it in requests, add the HTTP header `Authorization: Bearer ...` to any API call that requires OAuth \(i.e., one that is not publicly accessible\). Let's verify that our obtained credentials are working by calling [GET /api/v1/apps/verify\_credentials](../methods/apps/#verify-your-app-works): +The response of this method is a [Token]({{< relref "../entities/token.md" >}}) entity. We will need the `access_token` value. Once you have the access token, save it in your local cache. To use it in requests, add the HTTP header `Authorization: Bearer ...` to any API call that requires OAuth \(i.e., one that is not publicly accessible\). Let's verify that our obtained credentials are working by calling [GET /api/v1/apps/verify\_credentials]({{< relref "../methods/apps.md#verify-your-app-works" >}}): ```bash curl \ @@ -64,5 +64,5 @@ If we've obtained our token and formatted our request correctly, we should see o ## What we can do with authentication {#methods} -With our authenticated client application, we can view relations of an account with [GET /api/v1/accounts/:id/following](../methods/accounts/#following) and [GET /api/v1/accounts/:id/followers](../methods/accounts/#followers). Also, some instances may require authentication for methods that would otherwise be public, so if you encountered any authentication errors while playing around with public methods, then those methods should now work. +With our authenticated client application, we can view relations of an account with [GET /api/v1/accounts/:id/following]({{< relref "../methods/accounts.md#following" >}}) and [GET /api/v1/accounts/:id/followers]({{< relref "../methods/accounts.md#followers" >}}). Also, some instances may require authentication for methods that would otherwise be public, so if you encountered any authentication errors while playing around with public methods, then those methods should now work. diff --git a/content/en/entities/account.md b/content/en/entities/account.md index e14428b5..261faa5f 100644 --- a/content/en/entities/account.md +++ b/content/en/entities/account.md @@ -159,7 +159,7 @@ Equal to `header` if its value is a static image; different if `header` is an an ### `emojis` {#emojis} **Description:** Custom emoji entities to be used when rendering the profile. If none, an empty array will be returned.\ -**Type:** Array of [Emoji](emoji.md)\ +**Type:** Array of [Emoji]({{< relref "emoji.md" >}})\ **Version history:**\ 2.4.0 - added @@ -214,7 +214,7 @@ Equal to `header` if its value is a static image; different if `header` is an an ### `moved` {#moved} **Description:** Indicates that the profile is currently inactive and that its user has moved to a new account.\ -**Type:** [Account](account.md)\ +**Type:** [Account]({{< relref "account.md" >}})\ **Version history:**\ 2.1.0 - added @@ -234,8 +234,8 @@ Equal to `header` if its value is a static image; different if `header` is an an ### `source` {#source} -**Description:** An extra entity to be used with API methods to [verify credentials](../methods/accounts/#verify-account-credentials) and [update credentials](../methods/accounts/#update-account-credentials).\ -**Type:** [Source](source.md)\ +**Description:** An extra entity to be used with API methods to [verify credentials]({{< relref "../methods/accounts/#verify-account-credentials" >}}) and [update credentials]({{< relref "../methods/accounts/#update-account-credentials" >}}).\ +**Type:** [Source]({{< relref "source.md" >}})\ **Version history:**\ 2.4.0 - added diff --git a/content/en/entities/activity.md b/content/en/entities/activity.md index 0b014fe1..e2ebaacf 100644 --- a/content/en/entities/activity.md +++ b/content/en/entities/activity.md @@ -45,7 +45,7 @@ menu: ## See also -* [GET /api/v1/instance/activity](../methods/instance/#weekly-activity) +* [GET /api/v1/instance/activity]({{< relref "../methods/instance/#weekly-activity" >}}) {{< page-ref page="methods/instance.md" >}} diff --git a/content/en/entities/admin-report.md b/content/en/entities/admin-report.md index 4135fdbf..4b9f3e56 100644 --- a/content/en/entities/admin-report.md +++ b/content/en/entities/admin-report.md @@ -47,19 +47,19 @@ menu: ### `account` {#account} **Description:** The account which filed the report.\ -**Type:** [Account](account.md)\ +**Type:** [Account]({{< relref "account.md" >}})\ **Version history:** Added in 2.9.1 ### `target_account` {#target_account} **Description:** The account being reported.\ -**Type:** [Account](account.md)\ +**Type:** [Account]({{< relref "account.md" >}})\ **Version history:** Added in 2.9.1 ### `assigned_account` {#assigned_account} **Description:** The account of the moderator assigned to this report.\ -**Type:** [Account](account.md)\ +**Type:** [Account]({{< relref "account.md" >}})\ **Version history:** Added in 2.9.1 ### `action_taken_by_account` {#action_taken_by_account} @@ -71,7 +71,7 @@ menu: ### `statuses` {#statuses} **Description:** Statuses attached to the report, for context.\ -**Type:** Array of [Status](status.md)\ +**Type:** Array of [Status]({{< relref "status.md" >}})\ **Version history:** Added in 2.9.1 ## See also diff --git a/content/en/entities/application.md b/content/en/entities/application.md index 7860f03b..3223fe3b 100644 --- a/content/en/entities/application.md +++ b/content/en/entities/application.md @@ -34,7 +34,7 @@ menu: ### `vapid_key` {#vapid_key} -**Description:** Used for Push Streaming API. Returned with [POST /api/v1/apps](../methods/apps/#create-an-application). Equivalent to [PushSubscription\#server\_key](push-subscription.md#server_key)\ +**Description:** Used for Push Streaming API. Returned with [POST /api/v1/apps]({{< relref "../methods/apps/#create-an-application" >}}). Equivalent to [PushSubscription\#server\_key]({{< relref "pushsubscription.md#server_key" >}})\ **Type:** String\ **Version history:** Added in 2.8.0 @@ -54,8 +54,8 @@ menu: ## See also -* [Status\#application](status.md#application) -* [Create an application \(POST /api/v1/apps\)](../methods/apps/#create-an-application) +* [Status\#application]({{< relref "status.md#application" >}}) +* [Create an application \(POST /api/v1/apps\)]({{< relref "../methods/apps/#create-an-application" >}}) {{< page-ref page="status.md" >}} diff --git a/content/en/entities/attachment.md b/content/en/entities/attachment.md index 6c801240..a2406d6b 100644 --- a/content/en/entities/attachment.md +++ b/content/en/entities/attachment.md @@ -199,7 +199,7 @@ menu: May contain subtrees `small` and `original`, as well as various other top-level properties. -More importantly, there may be another top-level `focus` Hash object as of 2.3.0, with coordinates can be used for smart thumbnail cropping -- see [Focal points](../methods/statuses/media.md#focal-points) for more. +More importantly, there may be another top-level `focus` Hash object as of 2.3.0, with coordinates can be used for smart thumbnail cropping -- see [Focal points]({{< relref "../methods/statuses/media.md#focal-points" >}}) for more. ### `description` {#description} diff --git a/content/en/entities/context.md b/content/en/entities/context.md index 211cfb5c..f0f4dfff 100644 --- a/content/en/entities/context.md +++ b/content/en/entities/context.md @@ -47,18 +47,18 @@ menu: ### `ancestors` {#ancestors} **Description:** Parents in the thread.\ -**Type:** Array of [Status](status.md)\ +**Type:** Array of [Status]({{< relref "status.md" >}})\ **Version history:** Added in 0.6.0 ### `descendants` {#descendants} **Description:** Children in the thread.\ -**Type:** Array of [Status](status.md)\ +**Type:** Array of [Status]({{< relref "status.md" >}})\ **Version history:** Added in 0.6.0 ## See also -* [GET /api/v1/statuses/:id/context](../methods/statuses/#parent-and-child-statuses) +* [GET /api/v1/statuses/:id/context]({{< relref "../methods/statuses/#parent-and-child-statuses" >}}) {{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/serializers/rest/context_serializer.rb" caption="app/serializers/rest/context\_serializer.rb" >}} diff --git a/content/en/entities/conversation.md b/content/en/entities/conversation.md index 66bcd4f1..cf5b9b07 100644 --- a/content/en/entities/conversation.md +++ b/content/en/entities/conversation.md @@ -41,7 +41,7 @@ menu: ### `accounts` {#accounts} **Description:** Participants in the conversation.\ -**Type:** Array of [Account](account.md)\ +**Type:** Array of [Account]({{< relref "account.md" >}})\ **Version history:** Added in 2.6.0 ### `unread` {#unread} @@ -55,7 +55,7 @@ menu: ### `last_status` {#last_status} **Description:** The last status in the conversation, to be used for optional display.\ -**Type:** [Status](status.md)\ +**Type:** [Status]({{< relref "status.md" >}})\ **Version history:** Added in 2.6.0 ## See also diff --git a/content/en/entities/emoji.md b/content/en/entities/emoji.md index 2af7c72f..dd37a45a 100644 --- a/content/en/entities/emoji.md +++ b/content/en/entities/emoji.md @@ -54,7 +54,7 @@ menu: ## See also -* [Status\#emojis](status.md#emojis) +* [Status\#emojis]({{< relref "status.md#emojis" >}}) {{< page-ref page="status.md" >}} diff --git a/content/en/entities/field.md b/content/en/entities/field.md index c7a7a106..0e2b050a 100644 --- a/content/en/entities/field.md +++ b/content/en/entities/field.md @@ -59,8 +59,8 @@ menu: ## See also -* [Account\#fields](account.md#fields) -* [Source\#fields](source.md#fields) +* [Account\#fields]({{< relref "account.md#fields" >}}) +* [Source\#fields]({{< relref "source.md#fields" >}}) {{< page-ref page="account.md" >}} diff --git a/content/en/entities/history.md b/content/en/entities/history.md index 6082851a..10561d18 100644 --- a/content/en/entities/history.md +++ b/content/en/entities/history.md @@ -38,7 +38,7 @@ menu: ## See also -* [Tag\#history](tag.md#history) +* [Tag\#history]({{< relref "tag.md#history" >}}) {{< page-ref page="tag.md" >}} diff --git a/content/en/entities/identityproof.md b/content/en/entities/identityproof.md index b4e86d74..88c3677b 100644 --- a/content/en/entities/identityproof.md +++ b/content/en/entities/identityproof.md @@ -50,9 +50,9 @@ menu: ## See also -* [GET /api/v1/accounts/:id/identity\_proofs](../methods/accounts/#identity-proofs) +* [GET /api/v1/accounts/:id/identity\_proofs]({{< relref "../methods/accounts/#identity-proofs" >}}) * /api/proofs -* [About identity proofs](../user/contacts.md#identity-proofs) +* [About identity proofs]({{< relref "../user/contacts.md#identity-proofs" >}}) {{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/serializers/rest/identity_proof_serializer.rb" caption="app/serializers/rest/identity\_proof\_serializer.rb" >}} diff --git a/content/en/entities/instance.md b/content/en/entities/instance.md index 97aa7d82..681a5f37 100644 --- a/content/en/entities/instance.md +++ b/content/en/entities/instance.md @@ -166,7 +166,7 @@ Domains federated with this instance. Number. ### `contact_account` {#contact_account} **Description:** A user that can be contacted, as an alternative to `email`.\ -**Type:** [Account](account.md) or null\ +**Type:** [Account]({{< relref "account.md" >}}) or null\ **Version history:** Added in 2.3.0 ## See also diff --git a/content/en/entities/mention.md b/content/en/entities/mention.md index 7a03864d..3f3a51d6 100644 --- a/content/en/entities/mention.md +++ b/content/en/entities/mention.md @@ -57,8 +57,8 @@ menu: ## See also -* [GET /api/v1/statuses/:id](../methods/statuses/#view-specific-status) -* [Status\#mentions](status.md#mentions) +* [GET /api/v1/statuses/:id]({{< relref "../methods/statuses/#view-specific-status" >}}) +* [Status\#mentions]({{< relref "status.md#mentions" >}}) {{< page-ref page="status.md" >}} diff --git a/content/en/entities/notification.md b/content/en/entities/notification.md index e14434f6..223a7727 100644 --- a/content/en/entities/notification.md +++ b/content/en/entities/notification.md @@ -91,7 +91,7 @@ menu: ### `account` {#account} **Description:** The account that performed the action that generated the notification.\ -**Type:** [Account](account.md)\ +**Type:** [Account]({{< relref "account.md" >}})\ **Version history:**\ 0.9.9 - added @@ -100,7 +100,7 @@ menu: ### `status` {#status} **Description:** Status that was the object of the notification, e.g. in mentions, reblogs, favourites, or polls.\ -**Type:** [Status](status.md)\ +**Type:** [Status]({{< relref "status.md" >}})\ **Version history:**\ 0.9.9 - added diff --git a/content/en/entities/poll.md b/content/en/entities/poll.md index 5c182c51..82470f05 100644 --- a/content/en/entities/poll.md +++ b/content/en/entities/poll.md @@ -106,7 +106,7 @@ The number of received votes for this option. Number, or null if results are not ## See also -* [Status\#poll](status.md#poll) +* [Status\#poll]({{< relref "status.md#poll" >}}) * [/api/v1/polls]({{< relref "../methods/statuses/polls.md" >}}) {{< page-ref page="status.md" >}} diff --git a/content/en/entities/preferences.md b/content/en/entities/preferences.md index fae5a329..7623bdb3 100644 --- a/content/en/entities/preferences.md +++ b/content/en/entities/preferences.md @@ -22,7 +22,7 @@ menu: ### `posting:default:visibility` {#visibility} -**Description:** Default visibility for new posts. Equivalent to [Source\#privacy](source.md#privacy).\ +**Description:** Default visibility for new posts. Equivalent to [Source\#privacy]({{< relref "source.md#privacy" >}}).\ **Type:** String \(Enumerable, oneOf\)\ `public` = Public post\ `unlisted` = Unlisted post\ @@ -32,13 +32,13 @@ menu: ### `posting:default:sensitive` {#sensitive} -**Description:** Default sensitivity flag for new posts. Equivalent to [Source\#sensitive](source.md#sensitive).\ +**Description:** Default sensitivity flag for new posts. Equivalent to [Source\#sensitive]({{< relref "source.md#sensitive" >}}).\ **Type:** Boolean\ **Version history:** Added in 2.8.0 ### `posting:default:language` {#language} -**Description:** Default language for new posts. Equivalent to [Source\#language](source.md#language)\ +**Description:** Default language for new posts. Equivalent to [Source\#language]({{< relref "source.md#language" >}})\ **Type:** String \(ISO 639-1 language two-letter code\), or null\ **Version history:** Added in 2.8.0 @@ -59,9 +59,9 @@ menu: ## See also -* [GET /api/v1/accounts/verify\_credentials](../methods/accounts/#verify-account-credentials) -* [PATCH /api/v1/accounts/update\_credentials](../methods/accounts/#update-account-credentials) -* [GET /api/v1/preferences](../methods/accounts/preferences.md#view-user-preferences) +* [GET /api/v1/accounts/verify\_credentials]({{< relref "../methods/accounts.md#verify-account-credentials" >}}) +* [PATCH /api/v1/accounts/update\_credentials]({{< relref "../methods/accounts.md#update-account-credentials" >}}) +* [GET /api/v1/preferences]({{< relref "../methods/accounts/preferences.md#view-user-preferences" >}}) {{< page-ref page="methods/accounts/preferences.md" >}} diff --git a/content/en/entities/relationship.md b/content/en/entities/relationship.md index 6e497f33..b8b45af7 100644 --- a/content/en/entities/relationship.md +++ b/content/en/entities/relationship.md @@ -112,7 +112,7 @@ menu: ## See also -* [GET /api/v1/accounts/relationships](../methods/accounts/#check-relationships-to-other-accounts) +* [GET /api/v1/accounts/relationships]({{< relref "../methods/accounts.d#check-relationships-to-other-accounts" >}}) {{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/app/serializers/rest/relationship_serializer.rb" caption="app/serializers/rest/relationship\_serializer.rb" >}} diff --git a/content/en/entities/results.md b/content/en/entities/results.md index ea5aeb8d..23c75da1 100644 --- a/content/en/entities/results.md +++ b/content/en/entities/results.md @@ -88,19 +88,19 @@ menu: ### `accounts` {#accounts} **Description:** Accounts which match the given query\ -**Type:** Array of [Account](account.md)\ +**Type:** Array of [Account]({{< relref "account.md" >}})\ **Version history:** Added in x.x.x ### `statuses` {#statuses} **Description:** Statuses which match the given query\ -**Type:** Array of [Status](status.md)\ +**Type:** Array of [Status]({{< relref "status.md" >}})\ **Version history:** Added in x.x.x ### `hashtags` {#hashtags} **Description:** Hashtags which match the given query\ -**Type:** Array of [Tag](tag.md) \(v2\). Array of String \(v1\).\ +**Type:** Array of [Tag]({{< relref "tag.md" >}}) \(v2\). Array of String \(v1\).\ **Version history:** v1 added in 1.1.0 and deprecated in 3.0.0. v2 added in 2.4.1 and replaced v1 in 3.0.0. ## See also diff --git a/content/en/entities/source.md b/content/en/entities/source.md index c79e9e8a..e835c005 100644 --- a/content/en/entities/source.md +++ b/content/en/entities/source.md @@ -88,9 +88,9 @@ menu: ## See also -* [Account\#source](account.md#source) -* [POST /api/v1/accounts/verify\_credentials](../methods/accounts/#verify-account-credentials) -* [PATCH /api/v1/accounts/update\_credentials](../methods/accounts/#update-account-credentials) +* [Account\#source]({{< relref "account.md#source" >}}) +* [POST /api/v1/accounts/verify\_credentials]({{< relref "../methods/accounts.md#verify-account-credentials" >}}) +* [PATCH /api/v1/accounts/update\_credentials]({{< relref "../methods/accounts.md#update-account-credentials" >}}) {{< page-ref page="account.md" >}} diff --git a/content/en/entities/status.md b/content/en/entities/status.md index 75fed88f..7ae2eb0b 100644 --- a/content/en/entities/status.md +++ b/content/en/entities/status.md @@ -153,7 +153,7 @@ menu: ### `application` {#application} **Description:** The application used to post this status.\ -**Type:** [Application]({{< relref "application.md" >}}%)\ +**Type:** [Application]({{< relref "application.md" >}})\ **Version history:** Added in 0.9.9 ## Rendering attributes diff --git a/content/en/entities/tag.md b/content/en/entities/tag.md index 6982e6fd..951da20e 100644 --- a/content/en/entities/tag.md +++ b/content/en/entities/tag.md @@ -76,8 +76,8 @@ menu: ## See also -* [Status\#tags](status.md#tags) -* [GET /api/v1/featured\_tags/suggestions](../methods/accounts/featured_tags.md#suggested-tags-to-feature) +* [Status\#tags]({{< relref "status.md#tags" >}}) +* [GET /api/v1/featured\_tags/suggestions]({{< relref "../methods/accounts/featured_tags.md#suggested-tags-to-feature" >}}) {{< page-ref page="status.md" >}} diff --git a/content/en/entities/token.md b/content/en/entities/token.md index e2a87d41..1e4883ad 100644 --- a/content/en/entities/token.md +++ b/content/en/entities/token.md @@ -45,9 +45,9 @@ menu: ## See also -* [Example authorization code flow](../client/token.md#example-authorization-code-flow) -* [OAuth Scopes](../api/oauth-scopes.md) -* [POST /oauth/token](../methods/apps/oauth.md#obtain-a-token) +* [Example authorization code flow]({{< relref "../client/token.md#example-authorization-code-flow" >}}) +* [OAuth Scopes]({{< relref "../api/oauth-scopes.md" >}}) +* [POST /oauth/token]({{< relref "../methods/apps/oauth.md#obtain-a-token" >}}) {{< page-ref page="methods/apps/oauth.md" >}} diff --git a/content/en/methods/statuses/media.md b/content/en/methods/statuses/media.md index d5635bf1..30dad166 100644 --- a/content/en/methods/statuses/media.md +++ b/content/en/methods/statuses/media.md @@ -393,7 +393,11 @@ File or file type is unsupported or invalid Server-side preview images are never cropped, to support a variety of apps and user interfaces. Therefore, the cropping must be done by those apps. To crop intelligently, focal points can be used to ensure a certain section of the image is always within the cropped viewport. [See this guide on how focal points are defined.](https://github.com/jonom/jquery-focuspoint#1-calculate-your-images-focus-point) In summary, floating points range from -1.0 to 1.0, left-to-right or bottom-to-top. \(0,0\) is the center of the image. \(0.5, 0.5\) would be in the center of the upper-right quadrant. \(-0.5, -0.5\) would be in the center of the lower-left quadrant. For reference, thumbnails in the Mastodon frontend are most commonly 16:9. -{{< figure src="..//assets/image%20%2856%29.png" caption="A demonstration of various focal points and their coordinates." >}} -{{< figure src="..//assets/image%20%2856%29.png" caption="A demonstration of various focal points and their coordinates." >}} +{{< figure src="/assets/image%20%2856%29.png" caption="A demonstration of various focal points and their coordinates." >}} + +{{< figure src="/assets/image%20%2856%29.png" caption="A demonstration of various focal points and their coordinates." >}} diff --git a/content/en/spec/activitypub.md b/content/en/spec/activitypub.md index 5cb34b84..743d41af 100644 --- a/content/en/spec/activitypub.md +++ b/content/en/spec/activitypub.md @@ -67,10 +67,10 @@ Some other Object types are converted as best as possible. The transformer uses | icon | Used as profile avatar. | | image | Used as profile header. | | manuallyApprovesFollowers | Will be shown as a locked account. | -| discoverable | Will be shown in the profile directory. See [Discoverability flag](activitypub.md#discoverable). | -| publicKey | Required for signatures. See [Public key](activitypub.md#public-key). | -| featured | Pinned posts. See [Featured collection](activitypub.md#featured). | -| attachment | Used for profile fields. See [Profile metadata](activitypub.md#profile-metadata) and [Identity proofs](activitypub.md#identityproof). | +| discoverable | Will be shown in the profile directory. See [Discoverability flag]({{< relref "activitypub.md#discoverable" >}}). | +| publicKey | Required for signatures. See [Public key]({{< relref "activitypub.md#public-key" >}}). | +| featured | Pinned posts. See [Featured collection]({{< relref "activitypub.md#featured" >}}). | +| attachment | Used for profile fields. See [Profile metadata]({{< relref "activitypub.md#profile-metadata" >}}) and [Identity proofs]({{< relref "activitypub.md#identityproof" >}}). | | alsoKnownAs | Required for Move activity. | ## HTML sanitization {#sanitization} @@ -117,7 +117,7 @@ Contains ActivityStreams extended properties that have been proposed but not off ### 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. +Contains properties used for HTTPS Signatures and Linked Data Signatures. Also used for identity proofs. See [Security]({{< relref "security.md" >}}) for more information. * sec:publicKey * sec:publicKeyPem @@ -145,7 +145,7 @@ Contains properties used for profile metadata. ### 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: +Public keys are used for HTTPS Signatures and Linked Data Signatures. This is implemented using an extra property `publicKey` on actor objects. See [Security]({{< relref "security.md" >}}) for more information. Example: ```javascript { @@ -220,7 +220,7 @@ Mastodon supports arbitrary emojis, that is, small images uploaded by admins and ### 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: +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]({{< relref "../methods/statuses/media.md#focal-points" >}}) for more information. Example: ```javascript { diff --git a/content/en/spec/oauth.md b/content/en/spec/oauth.md index 01cd51b4..26d85c94 100644 --- a/content/en/spec/oauth.md +++ b/content/en/spec/oauth.md @@ -17,7 +17,7 @@ Mastodon supports the following OAuth 2 flows: * **Password grant flow**: For bots and other single-user applications * **Client credentials flow**: For applications that do not act on behalf of users -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" >}}). +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]({{< relref "../methods/apps/#create-an-application" >}}) and then [proceed with normal OAuth 2]({{< relref "../methods/apps/oauth.md" >}}). ## OAuth 2 endpoints implemented {#implementation} @@ -25,15 +25,15 @@ The following descriptions are taken from the [Doorkeeper documentation](https:/ {{< caption-link url="https://github.com/tootsuite/mastodon/blob/master/config/initializers/doorkeeper.rb" caption="Doorkeeper config initializer" >}} -### [GET /oauth/authorize](../methods/apps/oauth.md#authorize-a-user) +### [GET /oauth/authorize]({{< relref "../methods/apps/oauth.md#authorize-a-user" >}}) 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) {#post-oauth-token} +### [POST /oauth/token]({{< relref "../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) {#post-oauth-revoke} +### [POST /oauth/revoke]({{< relref "../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\). diff --git a/content/en/spec/security.md b/content/en/spec/security.md index b4d9d510..3e551f6c 100644 --- a/content/en/spec/security.md +++ b/content/en/spec/security.md @@ -28,7 +28,7 @@ headers="(request-target) host date", signature="Y2FiYW...IxNGRiZDk4ZA==" ``` -The `keyId` should correspond to the actor and the key being used to generate the `signature`, whose value is equal to all parameters in `headers` concatenated together and signed by the key, then Base64-encoded. See [ActivityPub > Public key](activitypub.md#public-key) for more information on actor keys. An example key looks like this: +The `keyId` should correspond to the actor and the key being used to generate the `signature`, whose value is equal to all parameters in `headers` concatenated together and signed by the key, then Base64-encoded. See [ActivityPub > Public key]({{< relref "activitypub.md#public-key" >}}) for more information on actor keys. An example key looks like this: ```javascript "publicKey": { @@ -101,7 +101,7 @@ Mastodon verifies the signature using the following algorithm: [Linked Data Signatures 1.0](https://w3c-dvcg.github.io/ld-signatures/) is a specification for attaching cryptographic signatures to JSON-LD documents. LD Signatures are not used widely within Mastodon, but they are used in the following situations: -* 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 running a [self-destruct]({{< relref "../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 {#ld-sign}