From d3045cd4805b4834b2a51918ec47ad8ab7a9fa46 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 7 Jan 2026 16:31:55 +0000 Subject: [PATCH] Replace manual notes in documentation with admonitions As they're generally prettier. Requires https://github.com/element-hq/synapse/pull/19356 --- docs/admin_api/account_validity.md | 3 +- .../admin_api/client_server_api_extensions.md | 5 +- docs/admin_api/register_api.md | 3 +- docs/admin_api/rooms.md | 23 +++-- docs/admin_api/statistics.md | 7 +- docs/admin_api/user_admin_api.md | 86 +++++++++++-------- docs/delegate.md | 7 +- docs/modules/index.md | 9 +- docs/modules/media_repository_callbacks.md | 28 +++--- docs/modules/ratelimit_callbacks.md | 7 +- docs/modules/spam_checker_callbacks.md | 15 ++-- docs/modules/third_party_rules_callbacks.md | 14 ++- docs/openid.md | 5 +- docs/presence_router_module.md | 9 +- docs/setup/installation.md | 12 +-- docs/spam_checker.md | 9 +- docs/tcp_replication.md | 6 +- docs/turn-howto.md | 5 +- docs/upgrade.md | 9 +- .../admin_api/background_updates.md | 6 +- .../administration/admin_api/federation.md | 10 ++- .../admin_api/registration_tokens.md | 3 +- docs/usage/administration/admin_faq.md | 3 +- .../administration/monthly_active_users.md | 5 +- .../administration/useful_sql_for_admins.md | 3 +- .../user_authentication/refresh_tokens.md | 12 +-- docs/workers.md | 5 +- 27 files changed, 171 insertions(+), 138 deletions(-) diff --git a/docs/admin_api/account_validity.md b/docs/admin_api/account_validity.md index dfa69e515b..f8647225e2 100644 --- a/docs/admin_api/account_validity.md +++ b/docs/admin_api/account_validity.md @@ -1,6 +1,7 @@ # Account validity API -**Note:** This API is disabled when MSC3861 is enabled. [See #15582](https://github.com/matrix-org/synapse/pull/15582) +> [!NOTE] +> This API is disabled when MSC3861 is enabled. [See #15582](https://github.com/matrix-org/synapse/pull/15582) This API allows a server administrator to manage the validity of an account. To use it, you must enable the account validity feature (under diff --git a/docs/admin_api/client_server_api_extensions.md b/docs/admin_api/client_server_api_extensions.md index 08fac6289b..ed992fce2e 100644 --- a/docs/admin_api/client_server_api_extensions.md +++ b/docs/admin_api/client_server_api_extensions.md @@ -22,8 +22,9 @@ To receive soft failed events in APIs like `/sync` and `/messages`, set `return_ to `true` in the admin client config. When `false`, the normal behaviour of these endpoints is to exclude soft failed events. -**Note**: If the policy server flagged the event as spam and that caused soft failure, that will be indicated -in the event's `unsigned` content like so: +> [!NOTE] +> If the policy server flagged the event as spam and that caused soft failure, that will be indicated +> in the event's `unsigned` content like so: ```json { diff --git a/docs/admin_api/register_api.md b/docs/admin_api/register_api.md index e9a235ada5..69b4ccb9b7 100644 --- a/docs/admin_api/register_api.md +++ b/docs/admin_api/register_api.md @@ -1,6 +1,7 @@ # Shared-Secret Registration -**Note:** This API is disabled when MSC3861 is enabled. [See #15582](https://github.com/matrix-org/synapse/pull/15582) +> [!NOTE] +> This API is disabled when MSC3861 is enabled. [See #15582](https://github.com/matrix-org/synapse/pull/15582) This API allows for the creation of users in an administrative and non-interactive way. This is generally used for bootstrapping a Synapse diff --git a/docs/admin_api/rooms.md b/docs/admin_api/rooms.md index 11e787c236..cd48e697c0 100644 --- a/docs/admin_api/rooms.md +++ b/docs/admin_api/rooms.md @@ -703,7 +703,8 @@ The parameters and response values have the same format as ## Version 2 (new version) -**Note**: This API is new, experimental and "subject to change". +> [!NOTE] +> This API is new, experimental and "subject to change". This version works asynchronously, meaning you get the response from server immediately while the server works on that task in background. You can then request the status of the action @@ -770,7 +771,8 @@ The JSON body must not be empty. The body must be at least `{}`. ## Status of deleting rooms -**Note**: This API is new, experimental and "subject to change". +> [!NOTE] +> This API is new, experimental and "subject to change". It is possible to query the status of the background task for deleting rooms. The status can be queried up to 24 hours after completion of the task, @@ -883,8 +885,9 @@ The following fields are returned in the JSON response body: - `error` - A string that shows an error message if `status` is `failed`. Otherwise this field is hidden. - `shutdown_room` - An object containing information about the result of shutting down the room. - *Note:* The result is shown after removing the room members. - The delete process can still be running. Please pay attention to the `status`. + > [!NOTE] + > The result is shown after removing the room members. + > The delete process can still be running. Please pay attention to the `status`. - `kicked_users` - An array of users (`user_id`) that were kicked. - `failed_to_kick_users` - An array of users (`user_id`) that that were not kicked. - `local_aliases` - An array of strings representing the local aliases that were @@ -894,8 +897,9 @@ The following fields are returned in the JSON response body: ## Undoing room deletions -*Note*: This guide may be outdated by the time you read it. By nature of room deletions being performed at the database level, -the structure can and does change without notice. +> [!NOTE] +> This guide may be outdated by the time you read it. By nature of room deletions being performed at the database level, +> the structure can and does change without notice. First, it's important to understand that a room deletion is very destructive. Undoing a deletion is not as simple as pretending it never happened - work has to be done to move forward instead of resetting the past. In fact, in some cases it might not be possible @@ -978,9 +982,10 @@ A response as follows will be returned: ## Deleting forward extremities -**WARNING**: Please ensure you know what you're doing and have read -the related issue [#1760](https://github.com/matrix-org/synapse/issues/1760). -Under no situations should this API be executed as an automated maintenance task! +> [!WARNING] +> Please ensure you know what you're doing and have read +> the related issue [#1760](https://github.com/matrix-org/synapse/issues/1760). +> Under no situations should this API be executed as an automated maintenance task! If a room has lots of forward extremities, the extra can be deleted as follows: diff --git a/docs/admin_api/statistics.md b/docs/admin_api/statistics.md index 59f07311eb..8d958ad27d 100644 --- a/docs/admin_api/statistics.md +++ b/docs/admin_api/statistics.md @@ -92,9 +92,10 @@ This does not include the size of any associated media associated with the room. Returns an error on SQLite. -*Note:* This uses the planner statistics from PostgreSQL to do the estimates, -which means that the returned information can vary widely from reality. However, -it should be enough to get a rough idea of where database disk space is going. +> [!NOTE] +> This uses the planner statistics from PostgreSQL to do the estimates, +> which means that the returned information can vary widely from reality. However, +> it should be enough to get a rough idea of where database disk space is going. The API is: diff --git a/docs/admin_api/user_admin_api.md b/docs/admin_api/user_admin_api.md index 9e0a1cb70c..2d7f0bb3e4 100644 --- a/docs/admin_api/user_admin_api.md +++ b/docs/admin_api/user_admin_api.md @@ -137,8 +137,9 @@ Body parameters: - `address` - **string**, required. The third-party ID itself, e.g. `alice@example.com` for `email` or `447470274584` (for a phone number with country code "44") and `19254857364` (for a phone number with country code "1") for `msisdn`. - Note: If a threepid is removed from a user via this option, Synapse will also attempt to remove - that threepid from any identity servers it is aware has a binding for it. + > [!NOTE] + > If a threepid is removed from a user via this option, Synapse will also attempt to remove + > that threepid from any identity servers it is aware has a binding for it. - `external_ids` - **array**, optional. Allow setting the identifier of the external identity provider for SSO (Single sign-on). More details are in the configuration manual under the sections [sso](../usage/configuration/config_documentation.md#sso) and [oidc_providers](../usage/configuration/config_documentation.md#oidc_providers). @@ -151,15 +152,14 @@ Body parameters: granting them access to the Admin API, among other things. - `deactivated` - **bool**, optional. If unspecified, deactivation state will be left unchanged. - Note: - - For the password field there is no strict check of the necessity for its presence. - It is possible to have active users without a password, e.g. when authenticating with OIDC is configured. - You must check yourself whether a password is required when reactivating a user or not. - - It is not possible to set a password if the config option `password_config.localdb_enabled` is set `false`. - Users' passwords are wiped upon account deactivation, hence the need to set a new one here. - - Note: a user cannot be erased with this API. For more details on - deactivating and erasing users see [Deactivate Account](#deactivate-account). + > [!NOTE] + > - For the password field there is no strict check of the necessity for its presence. + > It is possible to have active users without a password, e.g. when authenticating with OIDC is configured. + > You must check yourself whether a password is required when reactivating a user or not. + > - It is not possible to set a password if the config option `password_config.localdb_enabled` is set `false`. + > Users' passwords are wiped upon account deactivation, hence the need to set a new one here. + > - A user cannot be erased with this API. For more details on + > deactivating and erasing users see [Deactivate Account](#deactivate-account). - `locked` - **bool**, optional. If unspecified, locked state will be left unchanged. - `user_type` - **string** or null, optional. If not provided, the user type will be not be changed. If `null` is given, the user type will be cleared. @@ -259,12 +259,15 @@ The following parameters should be set in the URL: Can be provided multiple times. Possible values are `bot`, `support` or "empty string". "empty string" here means to exclude users without a type. - `locked` - string representing a bool - Is optional and if `true` will **include** locked users. - Defaults to `false` to exclude locked users. Note: Introduced in v1.93. + Defaults to `false` to exclude locked users. + > [!NOTE] + > Introduced in v1.93. -Caution. The database only has indexes on the columns `name` and `creation_ts`. -This means that if a different sort order is used (`is_guest`, `admin`, -`user_type`, `deactivated`, `shadow_banned`, `avatar_url` or `displayname`), -this can cause a large load on the database, especially for large environments. +> [!CAUTION] +> The database only has indexes on the columns `name` and `creation_ts`. +> This means that if a different sort order is used (`is_guest`, `admin`, +> `user_type`, `deactivated`, `shadow_banned`, `avatar_url` or `displayname`), +> this can cause a large load on the database, especially for large environments. **Response** @@ -285,7 +288,9 @@ The following fields are returned in the JSON response body: - `avatar_url` - string - The user's avatar URL if they have set one. - `creation_ts` - integer - The user's creation timestamp in ms. - `last_seen_ts` - integer - The user's last activity timestamp in ms. - - `locked` - bool - Status if that user has been marked as locked. Note: Introduced in v1.93. + - `locked` - bool - Status if that user has been marked as locked. + > [!NOTE] + > Introduced in v1.93. - `next_token`: string representing a positive integer - Indication for pagination. See above. - `total` - integer - Total number of media. @@ -443,7 +448,8 @@ To unsuspend a user, use the same endpoint with a body of: ## Reset password -**Note:** This API is disabled when MSC3861 is enabled. [See #15582](https://github.com/matrix-org/synapse/pull/15582) +> [!NOTE] +> This API is disabled when MSC3861 is enabled. [See #15582](https://github.com/matrix-org/synapse/pull/15582) Changes the password of another user. This will automatically log the user out of all their devices. @@ -468,7 +474,8 @@ The parameter `logout_devices` is optional and defaults to `true`. ## Get whether a user is a server administrator or not -**Note:** This API is disabled when MSC3861 is enabled. [See #15582](https://github.com/matrix-org/synapse/pull/15582) +> [!NOTE] +> This API is disabled when MSC3861 is enabled. [See #15582](https://github.com/matrix-org/synapse/pull/15582) The api is: @@ -487,7 +494,8 @@ A response body like the following is returned: ## Change whether a user is a server administrator or not -**Note:** This API is disabled when MSC3861 is enabled. [See #15582](https://github.com/matrix-org/synapse/pull/15582) +> [!NOTE] +> This API is disabled when MSC3861 is enabled. [See #15582](https://github.com/matrix-org/synapse/pull/15582) Note that you cannot demote yourself. @@ -614,8 +622,9 @@ The following should be set as query parameters in the URL: invites sent at or after the provided timestamp will be returned. This works by comparing the provided timestamp to the `received_ts` column in the `events` table. - Note: https://currentmillis.com/ is a useful tool for converting dates - into timestamps and vice versa. + > [!NOTE] + > https://currentmillis.com/ is a useful tool for converting dates + > into timestamps and vice versa. A response body like the following is returned: @@ -648,8 +657,9 @@ The following should be set as query parameters in the URL: invites sent at or after the provided timestamp will be returned. This works by comparing the provided timestamp to the `received_ts` column in the `events` table. - Note: https://currentmillis.com/ is a useful tool for converting dates - into timestamps and vice versa. + > [!NOTE] + > https://currentmillis.com/ is a useful tool for converting dates + > into timestamps and vice versa. A response body like the following is returned: @@ -836,11 +846,12 @@ The following parameters should be set in the URL: If neither `order_by` nor `dir` is set, the default order is newest media on top (corresponds to `order_by` = `created_ts` and `dir` = `b`). -Caution. The database only has indexes on the columns `media_id`, -`user_id` and `created_ts`. This means that if a different sort order is used -(`upload_name`, `last_access_ts`, `media_length`, `media_type`, -`quarantined_by` or `safe_from_quarantine`), this can cause a large load on the -database, especially for large environments. +> [!CAUTION] +> The database only has indexes on the columns `media_id`, +> `user_id` and `created_ts`. This means that if a different sort order is used +> (`upload_name`, `last_access_ts`, `media_length`, `media_type`, +> `quarantined_by` or `safe_from_quarantine`), this can cause a large load on the +> database, especially for large environments. **Response** @@ -897,8 +908,9 @@ The following fields are returned in the JSON response body: * `deleted_media`: an array of strings - List of deleted `media_id` * `total`: integer - Total number of deleted `media_id` -**Note**: There is no `next_token`. This is not useful for deleting media, because -after deleting media the remaining media have a new order. +> [!NOTE] +> There is no `next_token`. This is not useful for deleting media, because +> after deleting media the remaining media have a new order. **Parameters** @@ -909,7 +921,8 @@ delete largest/smallest or newest/oldest files first. ## Login as a user -**Note:** This API is disabled when MSC3861 is enabled. [See #15582](https://github.com/matrix-org/synapse/pull/15582) +> [!NOTE] +> This API is disabled when MSC3861 is enabled. [See #15582](https://github.com/matrix-org/synapse/pull/15582) Get an access token that can be used to authenticate as that user. Useful for when admins wish to do actions on behalf of a user. @@ -940,9 +953,10 @@ tell they have been logged in as. To expire the token call the standard `/logout` API with the token. -Note: The token will expire if the *admin* user calls `/logout/all` from any -of their devices, but the token will *not* expire if the target user does the -same. +> [!NOTE] +> The token will expire if the *admin* user calls `/logout/all` from any +> of their devices, but the token will *not* expire if the target user does the +> same. ## Allow replacing master cross-signing key without User-Interactive Auth @@ -1598,5 +1612,3 @@ The following fields are returned in the JSON response body: the corresponding error that caused the redaction to fail _Added in Synapse 1.116.0._ - - diff --git a/docs/delegate.md b/docs/delegate.md index aee82fcb9a..b60d83d7db 100644 --- a/docs/delegate.md +++ b/docs/delegate.md @@ -63,9 +63,10 @@ file: serve_server_wellknown: true ``` -**Note**: this *only* works if `https://` is routed to Synapse, so is -generally not suitable if Synapse is hosted at a subdomain such as -`https://synapse.example.com`. +> [!NOTE] +> This *only* works if `https://` is routed to Synapse, so is +> generally not suitable if Synapse is hosted at a subdomain such as +> `https://synapse.example.com`. ## SRV DNS record delegation diff --git a/docs/modules/index.md b/docs/modules/index.md index 0a868b309f..76903d2bf6 100644 --- a/docs/modules/index.md +++ b/docs/modules/index.md @@ -2,10 +2,11 @@ Synapse supports extending its functionality by configuring external modules. -**Note**: When using third-party modules, you effectively allow someone else to run -custom code on your Synapse homeserver. Server admins are encouraged to verify the -provenance of the modules they use on their homeserver and make sure the modules aren't -running malicious code on their instance. +> [!NOTE] +> When using third-party modules, you effectively allow someone else to run +> custom code on your Synapse homeserver. Server admins are encouraged to verify the +> provenance of the modules they use on their homeserver and make sure the modules aren't +> running malicious code on their instance. ## Using modules diff --git a/docs/modules/media_repository_callbacks.md b/docs/modules/media_repository_callbacks.md index d7c9074bde..8c13f13a6f 100644 --- a/docs/modules/media_repository_callbacks.md +++ b/docs/modules/media_repository_callbacks.md @@ -14,10 +14,9 @@ _First introduced in Synapse v1.132.0_ async def get_media_config_for_user(user_id: str) -> JsonDict | None ``` -** -Caution: This callback is currently experimental . The method signature or behaviour -may change without notice. -** +> [!CAUTION] +> This callback is currently experimental. The method signature or behaviour +> may change without notice. Called when processing a request from a client for the [media config endpoint](https://spec.matrix.org/latest/client-server-api/#get_matrixclientv1mediaconfig). @@ -44,10 +43,9 @@ _First introduced in Synapse v1.132.0_ async def is_user_allowed_to_upload_media_of_size(user_id: str, size: int) -> bool ``` -** -Caution: This callback is currently experimental . The method signature or behaviour -may change without notice. -** +> [!CAUTION] +> This callback is currently experimental. The method signature or behaviour +> may change without notice. Called before media is accepted for upload from a user, in case the module needs to enforce a different limit for the particular user. @@ -73,10 +71,9 @@ _First introduced in Synapse v1.139.0_ async def get_media_upload_limits_for_user(user_id: str, size: int) -> list[synapse.module_api.MediaUploadLimit] | None ``` -** -Caution: This callback is currently experimental. The method signature or behaviour -may change without notice. -** +> [!CAUTION] +> This callback is currently experimental. The method signature or behaviour +> may change without notice. Called when processing a request to store content in the media repository. This can be used to dynamically override the [media upload limits configuration](../usage/configuration/config_documentation.html#media_upload_limits). @@ -108,10 +105,9 @@ _First introduced in Synapse v1.139.0_ async def on_media_upload_limit_exceeded(user_id: str, limit: synapse.module_api.MediaUploadLimit, sent_bytes: int, attempted_bytes: int) -> None ``` -** -Caution: This callback is currently experimental. The method signature or behaviour -may change without notice. -** +> [!CAUTION] +> This callback is currently experimental. The method signature or behaviour +> may change without notice. Called when a user attempts to upload media that would exceed a [configured media upload limit](../usage/configuration/config_documentation.html#media_upload_limits). diff --git a/docs/modules/ratelimit_callbacks.md b/docs/modules/ratelimit_callbacks.md index 048bdc6f9e..c6047aba71 100644 --- a/docs/modules/ratelimit_callbacks.md +++ b/docs/modules/ratelimit_callbacks.md @@ -14,10 +14,9 @@ _First introduced in Synapse v1.132.0_ async def get_ratelimit_override_for_user(user: str, limiter_name: str) -> synapse.module_api.RatelimitOverride | None ``` -** -Caution: This callback is currently experimental . The method signature or behaviour -may change without notice. -** +> [!CAUTION] +> This callback is currently experimental. The method signature or behaviour +> may change without notice. Called when constructing a ratelimiter of a particular type for a user. The module can return a `messages_per_second` and `burst_count` to be used, or `None` if diff --git a/docs/modules/spam_checker_callbacks.md b/docs/modules/spam_checker_callbacks.md index 0d261e844f..8754a42234 100644 --- a/docs/modules/spam_checker_callbacks.md +++ b/docs/modules/spam_checker_callbacks.md @@ -164,8 +164,9 @@ await user_may_send_3pid_invite( ) ``` -**Note**: If the third-party identifier is already associated with a matrix user ID, -[`user_may_invite`](#user_may_invite) will be used instead. +> [!NOTE] +> If the third-party identifier is already associated with a matrix user ID, +> [`user_may_invite`](#user_may_invite) will be used instead. The callback must return one of: - `synapse.module_api.NOT_SPAM`, to allow the operation. Other callbacks may still @@ -287,10 +288,9 @@ _First introduced in Synapse v1.132.0_ async def user_may_send_state_event(user_id: str, room_id: str, event_type: str, state_key: str, content: JsonDict) -> Union["synapse.module_api.NOT_SPAM", "synapse.module_api.errors.Codes"] ``` -** -Caution: This callback is currently experimental . The method signature or behaviour -may change without notice. -** +> [!CAUTION] +> This callback is currently experimental. The method signature or behaviour +> may change without notice. Called when processing a request to [send state events](https://spec.matrix.org/latest/client-server-api/#put_matrixclientv3roomsroomidstateeventtypestatekey) to a room. @@ -463,7 +463,8 @@ The value of the first callback that does not return `synapse.module_api.NOT_SPA be used. If this happens, Synapse will not call any of the subsequent implementations of this callback. -*Note:* This will not be called when a user registers. +> [!NOTE] +> This will not be called when a user registers. ## Example diff --git a/docs/modules/third_party_rules_callbacks.md b/docs/modules/third_party_rules_callbacks.md index 1474b2dfd5..1bbcd6b1fe 100644 --- a/docs/modules/third_party_rules_callbacks.md +++ b/docs/modules/third_party_rules_callbacks.md @@ -19,10 +19,9 @@ async def check_event_allowed( ) -> tuple[bool, dict | None] ``` -** -This callback is very experimental and can and will break without notice. Module developers -are encouraged to implement `check_event_for_spam` from the spam checker category instead. -** +> [!WARNING] +> This callback is very experimental and can and will break without notice. Module developers +> are encouraged to implement `check_event_for_spam` from the spam checker category instead. Called when processing any incoming event, with the event and a `StateMap` representing the current state of the room the event is being sent into. A `StateMap` is @@ -258,10 +257,9 @@ If multiple modules implement this callback, Synapse runs them all in order. _First introduced in Synapse v1.56.0_ -** -This callback is deprecated in favour of the `on_add_user_third_party_identifier` callback, which -features the same functionality. The only difference is in name. -** +> [!WARNING] +> This callback is deprecated in favour of the `on_add_user_third_party_identifier` callback, which +> features the same functionality. The only difference is in name. ```python async def on_threepid_bind(user_id: str, medium: str, address: str) -> None: diff --git a/docs/openid.md b/docs/openid.md index e91d375c41..3dcb076e02 100644 --- a/docs/openid.md +++ b/docs/openid.md @@ -190,8 +190,9 @@ oidc_providers: 3. Create an application for synapse in Authentik and link it to the provider. 4. Note the slug of your application, Client ID and Client Secret. -Note: RSA keys must be used for signing for Authentik, ECC keys do not work. -Note: The provider must have a signing key set and must not use an encryption key. +> [!NOTE] +> RSA keys must be used for signing for Authentik; ECC keys do not work. +> The provider must have a signing key set and must not use an encryption key. Synapse config: ```yaml diff --git a/docs/presence_router_module.md b/docs/presence_router_module.md index 092b566c5f..f0c555c351 100644 --- a/docs/presence_router_module.md +++ b/docs/presence_router_module.md @@ -1,8 +1,7 @@ -

-This page of the Synapse documentation is now deprecated. For up to date -documentation on setting up or writing a presence router module, please see -this page. -

+> [!WARNING] +> This page of the Synapse documentation is now deprecated. For up to date +> documentation on setting up or writing a presence router module, please see +> [this page](modules.md). # Presence Router Module diff --git a/docs/setup/installation.md b/docs/setup/installation.md index a48662362a..f43460b440 100644 --- a/docs/setup/installation.md +++ b/docs/setup/installation.md @@ -21,9 +21,10 @@ best practices. ⚠️ ## Installing Synapse -Note: Synapse uses a number of platform dependencies such as Python and PostgreSQL, -and aims to follow supported upstream versions. See the [deprecation -policy](../deprecation_policy.md) for more details. +> [!NOTE] +> Synapse uses a number of platform dependencies such as Python and PostgreSQL, +> and aims to follow supported upstream versions. See the [deprecation +> policy](../deprecation_policy.md) for more details. ### Prebuilt packages @@ -314,8 +315,9 @@ sudo dnf group install "Development Tools" ##### Red Hat Enterprise Linux / Rocky Linux / Oracle Linux -*Note: The term "RHEL" below refers to Red Hat Enterprise Linux, Oracle Linux and Rocky Linux. -The distributions are 1:1 binary compatible.* +> [!NOTE] +> The term "RHEL" below refers to Red Hat Enterprise Linux, Oracle Linux and Rocky Linux. +> The distributions are 1:1 binary compatible. It's recommended to use the latest Python versions. diff --git a/docs/spam_checker.md b/docs/spam_checker.md index ead0f03595..ffb20d2f59 100644 --- a/docs/spam_checker.md +++ b/docs/spam_checker.md @@ -1,8 +1,7 @@ -

-This page of the Synapse documentation is now deprecated. For up to date -documentation on setting up or writing a spam checker module, please see -this page. -

+> [!WARNING] +> This page of the Synapse documentation is now deprecated. For up to date +> documentation on setting up or writing a spam checker module, please see +> [this page](modules.md). # Handling spam in Synapse diff --git a/docs/tcp_replication.md b/docs/tcp_replication.md index c3b8c76609..ed4a9977fd 100644 --- a/docs/tcp_replication.md +++ b/docs/tcp_replication.md @@ -123,8 +123,10 @@ connection errors. The client should keep track of the token in the last RDATA command received for each stream so that on reconnection it can start streaming -from the correct place. Note: not all RDATA have valid tokens due to -batching. See `RdataCommand` for more details. +from the correct place. + +> [!NOTE] +> Not all RDATA have valid tokens due to batching. See `RdataCommand` for more details. ### Example diff --git a/docs/turn-howto.md b/docs/turn-howto.md index 9c1c6f4777..cf169e2661 100644 --- a/docs/turn-howto.md +++ b/docs/turn-howto.md @@ -156,8 +156,9 @@ Here are a few things to try: user=username:password ``` - **Note**: these settings will not take effect unless `use-auth-secret` - and `static-auth-secret` are disabled. + > [!NOTE] + > These settings will not take effect unless `use-auth-secret` + > and `static-auth-secret` are disabled. Restart coturn after changing the configuration file. diff --git a/docs/upgrade.md b/docs/upgrade.md index 5e7fa31580..8508b76148 100644 --- a/docs/upgrade.md +++ b/docs/upgrade.md @@ -2256,10 +2256,11 @@ default templates, see ## 3pid verification changes -**Note: As of this release, users will be unable to add phone numbers or -email addresses to their accounts, without changes to the Synapse -configuration. This includes adding an email address during -registration.** +> [!NOTE] +> As of this release, users will be unable to add phone numbers or +> email addresses to their accounts, without changes to the Synapse +> configuration. This includes adding an email address during +> registration. It is possible for a user to associate an email address or phone number with their account, for a number of reasons: diff --git a/docs/usage/administration/admin_api/background_updates.md b/docs/usage/administration/admin_api/background_updates.md index 7b75ee5587..616b7b1b69 100644 --- a/docs/usage/administration/admin_api/background_updates.md +++ b/docs/usage/administration/admin_api/background_updates.md @@ -49,9 +49,11 @@ This API allows pausing background updates. Background updates should *not* be paused for significant periods of time, as this can affect the performance of Synapse. -*Note*: This won't persist over restarts. +> [!NOTE] +> This won't persist over restarts. -*Note*: This won't cancel any update query that is currently running. This is +> [!NOTE] +> This won't cancel any update query that is currently running. This is usually fine since most queries are short lived, except for `CREATE INDEX` background updates which won't be cancelled once started. diff --git a/docs/usage/administration/admin_api/federation.md b/docs/usage/administration/admin_api/federation.md index ce735793c0..51fa2f029b 100644 --- a/docs/usage/administration/admin_api/federation.md +++ b/docs/usage/administration/admin_api/federation.md @@ -2,7 +2,8 @@ This API allows a server administrator to manage Synapse's federation with other homeservers. -Note: This API is new, experimental and "subject to change". +> [!NOTE] +> This API is new, experimental and "subject to change". ## List of destinations @@ -62,9 +63,10 @@ The following query parameters are available: - `dir` - Direction of room order. Either `f` for forwards or `b` for backwards. Setting this value to `b` will reverse the above sort order. Defaults to `f`. -*Caution:* The database only has an index on the column `destination`. -This means that if a different sort order is used, -this can cause a large load on the database, especially for large environments. +> [!CAUTION] +> The database only has an index on the column `destination`. +> This means that if a different sort order is used, +> this can cause a large load on the database, especially for large environments. **Response** diff --git a/docs/usage/administration/admin_api/registration_tokens.md b/docs/usage/administration/admin_api/registration_tokens.md index ba95bcf038..04847905d6 100644 --- a/docs/usage/administration/admin_api/registration_tokens.md +++ b/docs/usage/administration/admin_api/registration_tokens.md @@ -1,6 +1,7 @@ # Registration Tokens -**Note:** This API is disabled when MSC3861 is enabled. [See #15582](https://github.com/matrix-org/synapse/pull/15582) +> [!NOTE] +> This API is disabled when MSC3861 is enabled. [See #15582](https://github.com/matrix-org/synapse/pull/15582) This API allows you to manage tokens which can be used to authenticate registration requests, as proposed in diff --git a/docs/usage/administration/admin_faq.md b/docs/usage/administration/admin_faq.md index 20f8c6a157..6f5801d972 100644 --- a/docs/usage/administration/admin_faq.md +++ b/docs/usage/administration/admin_faq.md @@ -255,7 +255,8 @@ line to `/etc/default/matrix-synapse`: LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libjemalloc.so.2 -*Note*: You may need to set `PYTHONMALLOC=malloc` to ensure that `jemalloc` can accurately calculate memory usage. By default, Python uses its internal small-object allocator, which may interfere with jemalloc's ability to track memory consumption correctly. This could prevent the [cache_autotuning](../configuration/config_documentation.md#caches) feature from functioning as expected, as the Python allocator may not reach the memory threshold set by `max_cache_memory_usage`, thus not triggering the cache eviction process. +> [!NOTE] +> You may need to set `PYTHONMALLOC=malloc` to ensure that `jemalloc` can accurately calculate memory usage. By default, Python uses its internal small-object allocator, which may interfere with jemalloc's ability to track memory consumption correctly. This could prevent the [cache_autotuning](../configuration/config_documentation.md#caches) feature from functioning as expected, as the Python allocator may not reach the memory threshold set by `max_cache_memory_usage`, thus not triggering the cache eviction process. This made a significant difference on Python 2.7 - it's unclear how much of an improvement it provides on Python 3.x. diff --git a/docs/usage/administration/monthly_active_users.md b/docs/usage/administration/monthly_active_users.md index b1da6f17c2..b88c1aec7e 100644 --- a/docs/usage/administration/monthly_active_users.md +++ b/docs/usage/administration/monthly_active_users.md @@ -20,8 +20,9 @@ So for example, if Synapse were to calculate the active users on the 15th July a A user is **never** considered active if they are either: - Part of the trial day cohort (described below) - Owned by an application service. - - Note: This **only** covers users that are part of an application service `namespaces.users` registration. The namespace - must also be marked as `exclusive`. + > [!NOTE] + > This **only** covers users that are part of an application service `namespaces.users` registration. The namespace + > must also be marked as `exclusive`. Otherwise, any request to Synapse will mark the user as active. Please note that registration will not mark a user as active *unless* they register with a 3pid that is included in the config field `mau_limits_reserved_threepids`. diff --git a/docs/usage/administration/useful_sql_for_admins.md b/docs/usage/administration/useful_sql_for_admins.md index 41755cd3b6..a187590b6b 100644 --- a/docs/usage/administration/useful_sql_for_admins.md +++ b/docs/usage/administration/useful_sql_for_admins.md @@ -130,7 +130,8 @@ SELECT e.room_id, r.name, COUNT(e.event_id) cnt ``` ## Show top 20 users on homeserver by sent events (messages) at last month: -Caution. This query does not use any indexes, can be slow and create load on the database. +> [!CAUTION] +> This query does not use any indexes, can be slow and create load on the database. ```sql SELECT COUNT(*), sender FROM events diff --git a/docs/usage/configuration/user_authentication/refresh_tokens.md b/docs/usage/configuration/user_authentication/refresh_tokens.md index 23b3cddae0..f5e2f71efd 100644 --- a/docs/usage/configuration/user_authentication/refresh_tokens.md +++ b/docs/usage/configuration/user_authentication/refresh_tokens.md @@ -96,8 +96,9 @@ The following configuration options, in the `registration` section, are related: it more difficult for them to refresh in time, which may force them to need to re-authenticate using login credentials). -**Note:** All four options above only apply when tokens are created (by logging in or refreshing). -Changes to these settings do not apply retroactively. +> [!NOTE] +> All four options above only apply when tokens are created (by logging in or refreshing). +> Changes to these settings do not apply retroactively. ### Using refresh token expiry to log out inactive sessions @@ -113,9 +114,10 @@ account. `refreshable_access_token_lifetime` and this section assumes that to be the case for simplicity.) -Note: this will only affect sessions using refresh tokens. You may wish to -set a short `nonrefreshable_access_token_lifetime` to prevent this being bypassed -by clients that do not support refresh tokens. +> [!NOTE] +> This will only affect sessions using refresh tokens. You may wish to +> set a short `nonrefreshable_access_token_lifetime` to prevent this being bypassed +> by clients that do not support refresh tokens. #### Choosing values that guarantee permitting some inactivity diff --git a/docs/workers.md b/docs/workers.md index c2aef33e16..86c1f1a0a6 100644 --- a/docs/workers.md +++ b/docs/workers.md @@ -459,8 +459,9 @@ and be listed in the [`instance_map`](usage/configuration/config_documentation.m config. * Have the main process declared on the [`instance_map`](usage/configuration/config_documentation.md#instance_map) as well. -Note: The same worker can handle multiple streams, but unless otherwise documented, -each stream can only have a single writer. +> [!NOTE] +> The same worker can handle multiple streams, but unless otherwise documented, +> each stream can only have a single writer. For example, to move event persistence off to a dedicated worker, the shared configuration would include: