Changelog

```
dmr on titan in synapse/book on  dmr/docs-tidy via  v16.14.0 via 🐍 v3.10.7 (matrix-synapse-py3.10) via 🐏 12GiB/15GiB | 5GiB/8GiB took 8s
2022-10-24 15:15:53 ✔  $ linkchecker **.html
INFO linkcheck.cmdline 2022-10-24 15:16:33,785 MainThread Checking intern URLs only; use --check-extern to check extern URLs.
LinkChecker 10.1.0
Copyright (C) 2000-2016 Bastian Kleineidam, 2010-2021 LinkChecker Authors
LinkChecker comes with ABSOLUTELY NO WARRANTY!
This is free software, and you are welcome to redistribute it under
certain conditions. Look at the file `LICENSE' within this distribution.
Read the documentation at https://linkchecker.github.io/linkchecker/
Write comments and bugs to https://github.com/linkchecker/linkchecker/issues

Start checking at 2022-10-24 15:16:33+001
/usr/lib/python3.10/site-packages/bs4/__init__.py:435: MarkupResemblesLocatorWarning: The input looks more like a filename than markup. You may want to open this file and pass the filehandle into Beautiful Soup.
  warnings.warn(
10 threads active,    88 links queued,  241 links in 339 URLs checked, runtime 1 seconds

Statistics:
Downloaded: 4.04MB.
Content types: 7 image, 106 text, 0 video, 0 audio, 22 application, 3 mail and 508 other.
URL lengths: min=16, max=256, avg=67.

That's it. 646 links in 646 URLs checked. 0 warnings found. 0 errors found.
Stopped checking at 2022-10-24 15:16:39+001 (5 seconds)
```

changelog.d/14282.doc

@@ -0,0 +1 @@
+Reorganise documentation source files and fix dead links.

docker/README-testing.md

@@ -98,7 +98,7 @@ Dockerfile makes use of to generate appropriate worker, nginx and supervisord co
 files.
 
 Sharding is supported for a subset of workers, in line with the
-[worker documentation](../docs/workers.md). To run multiple instances of a given worker
+[worker documentation](../docs/usage/configuration/workers.md). To run multiple instances of a given worker
 type, simply specify the type multiple times in `SYNAPSE_WORKER_TYPES`
 (e.g `SYNAPSE_WORKER_TYPES=event_creator,event_creator...`).
 

docs/SUMMARY.md

@@ -5,38 +5,38 @@
 
 # Setup
   - [Installation](setup/installation.md)
-  - [Using Postgres](postgres.md)
+  - [Using Postgres](setup/postgres.md)
-  - [Configuring a Reverse Proxy](reverse_proxy.md)
+  - [Configuring a Reverse Proxy](setup/reverse_proxy.md)
   - [Configuring a Forward/Outbound Proxy](setup/forward_proxy.md)
-  - [Configuring a Turn Server](turn-howto.md)
+  - [Configuring a Turn Server](setup/turn-howto.md)
-  - [Delegation](delegate.md)
+  - [Delegation](setup/delegate.md)
 
 # Upgrading
   - [Upgrading between Synapse Versions](upgrade.md)
 
 # Usage
-  - [Federation](federate.md)
+  - [Federation](usage/federate.md)
   - [Configuration](usage/configuration/README.md)
     - [Configuration Manual](usage/configuration/config_documentation.md) 
     - [Homeserver Sample Config File](usage/configuration/homeserver_sample_config.md)
     - [Logging Sample Config File](usage/configuration/logging_sample_config.md)
-    - [Structured Logging](structured_logging.md)
+    - [Structured Logging](usage/configuration/structured_logging.md)
-    - [Templates](templates.md)
+    - [Templates](usage/configuration/templates.md)
     - [User Authentication](usage/configuration/user_authentication/README.md)
       - [Single-Sign On](usage/configuration/user_authentication/single_sign_on/README.md)
-        - [OpenID Connect](openid.md)
+        - [OpenID Connect](usage/configuration/user_authentication/single_sign_on/openid.md)
         - [SAML](usage/configuration/user_authentication/single_sign_on/saml.md)
         - [CAS](usage/configuration/user_authentication/single_sign_on/cas.md)
-        - [SSO Mapping Providers](sso_mapping_providers.md)
+        - [SSO Mapping Providers](usage/configuration/user_authentication/single_sign_on/sso_mapping_providers.md)
-      - [Password Auth Providers](password_auth_providers.md)
+      - [Password Auth Providers](usage/configuration/user_authentication/password_auth_providers.md)
-      - [JSON Web Tokens](jwt.md)
+      - [JSON Web Tokens](usage/configuration/user_authentication/jwt.md)
       - [Refresh Tokens](usage/configuration/user_authentication/refresh_tokens.md)
-    - [Registration Captcha](CAPTCHA_SETUP.md)
+    - [Registration Captcha](usage/configuration/CAPTCHA_SETUP.md)
-    - [Application Services](application_services.md)
+    - [Application Services](usage/configuration/application_services.md)
-    - [Server Notices](server_notices.md)
+    - [Server Notices](usage/configuration/server_notices.md)
-    - [Consent Tracking](consent_tracking.md)
+    - [Consent Tracking](usage/configuration/consent_tracking.md)
-    - [User Directory](user_directory.md)
+    - [User Directory](usage/configuration/user_directory.md)
-    - [Message Retention Policies](message_retention_policies.md)
+    - [Message Retention Policies](usage/configuration/message_retention_policies.md)
     - [Pluggable Modules](modules/index.md)
       - [Writing a module](modules/writing_a_module.md)
         - [Spam checker callbacks](modules/spam_checker_callbacks.md)
@@ -47,65 +47,65 @@
         - [Background update controller callbacks](modules/background_update_controller_callbacks.md)
         - [Account data callbacks](modules/account_data_callbacks.md)
         - [Porting a legacy module to the new interface](modules/porting_legacy_module.md)
-    - [Workers](workers.md)
+    - [Workers](usage/configuration/workers.md)
-      - [Using `synctl` with Workers](synctl_workers.md)
+      - [Using `synctl` with Workers](usage/configuration/synctl_workers.md)
-      - [Systemd](systemd-with-workers/README.md)
+      - [Systemd](usage/configuration/systemd-with-workers/README.md)
-  - [Administration](usage/administration/README.md)
+  - [Administration](administration/README.md)
-    - [Admin API](usage/administration/admin_api/README.md)
+    - [Admin API](administration/admin_api/README.md)
-      - [Account Validity](admin_api/account_validity.md)
+      - [Account Validity](administration/admin_api/account_validity.md)
-      - [Background Updates](usage/administration/admin_api/background_updates.md)
+      - [Background Updates](administration/admin_api/background_updates.md)
-      - [Event Reports](admin_api/event_reports.md)
+      - [Event Reports](administration/admin_api/event_reports.md)
-      - [Media](admin_api/media_admin_api.md)
+      - [Media](administration/admin_api/media_admin_api.md)
-      - [Purge History](admin_api/purge_history_api.md)
+      - [Purge History](administration/admin_api/purge_history_api.md)
-      - [Register Users](admin_api/register_api.md)
+      - [Register Users](administration/admin_api/register_api.md)
-      - [Registration Tokens](usage/administration/admin_api/registration_tokens.md)
+      - [Registration Tokens](administration/admin_api/registration_tokens.md)
-      - [Manipulate Room Membership](admin_api/room_membership.md)
+      - [Manipulate Room Membership](administration/admin_api/room_membership.md)
-      - [Rooms](admin_api/rooms.md)
+      - [Rooms](administration/admin_api/rooms.md)
-      - [Server Notices](admin_api/server_notices.md)
+      - [Server Notices](administration/admin_api/server_notices.md)
-      - [Statistics](admin_api/statistics.md)
+      - [Statistics](administration/admin_api/statistics.md)
-      - [Users](admin_api/user_admin_api.md)
+      - [Users](administration/admin_api/user_admin_api.md)
-      - [Server Version](admin_api/version_api.md)
+      - [Server Version](administration/admin_api/version_api.md)
-      - [Federation](usage/administration/admin_api/federation.md)
+      - [Federation](administration/admin_api/federation.md)
-    - [Manhole](manhole.md)
+    - [Manhole](administration/manhole.md)
-    - [Monitoring](metrics-howto.md)
+    - [Monitoring](administration/metrics-howto.md)
-      - [Reporting Homeserver Usage Statistics](usage/administration/monitoring/reporting_homeserver_usage_statistics.md)
+      - [Reporting Homeserver Usage Statistics](administration/reporting_homeserver_usage_statistics.md)
-    - [Monthly Active Users](usage/administration/monthly_active_users.md)
+    - [Monthly Active Users](administration/monthly_active_users.md)
-    - [Understanding Synapse Through Grafana Graphs](usage/administration/understanding_synapse_through_grafana_graphs.md)
+    - [Understanding Synapse Through Grafana Graphs](administration/understanding_synapse_through_grafana_graphs.md)
-    - [Useful SQL for Admins](usage/administration/useful_sql_for_admins.md)
+    - [Useful SQL for Admins](administration/useful_sql_for_admins.md)
-    - [Database Maintenance Tools](usage/administration/database_maintenance_tools.md)
+    - [Database Maintenance Tools](administration/database_maintenance_tools.md)
-    - [State Groups](usage/administration/state_groups.md)
+    - [State Groups](administration/state_groups.md)
-    - [Request log format](usage/administration/request_log.md)
+    - [Request log format](administration/request_log.md)
-    - [Admin FAQ](usage/administration/admin_faq.md)
+    - [Admin FAQ](administration/admin_faq.md)
     - [Scripts]()
 
 # Development
   - [Contributing Guide](development/contributing_guide.md)
-  - [Code Style](code_style.md)
+  - [Code Style](development/code_style.md)
   - [Reviewing Code](development/reviews.md)
   - [Release Cycle](development/releases.md)
   - [Git Usage](development/git.md)
   - [Testing]()
     - [Demo scripts](development/demo.md)
-  - [OpenTracing](opentracing.md)
+  - [OpenTracing](development/opentracing.md)
   - [Database Schemas](development/database_schema.md)
   - [Experimental features](development/experimental_features.md)
   - [Dependency management](development/dependencies.md)
   - [Synapse Architecture]()
     - [Cancellation](development/synapse_architecture/cancellation.md)
-    - [Log Contexts](log_contexts.md)
+    - [Log Contexts](development/synapse_architecture/log_contexts.md)
-    - [Replication](replication.md)
+    - [Replication](development/synapse_architecture/replication.md)
-    - [TCP Replication](tcp_replication.md)
+    - [TCP Replication](development/synapse_architecture/tcp_replication.md)
   - [Internal Documentation](development/internal_documentation/README.md)
     - [Single Sign-On]()
-      - [SAML](development/saml.md)
+      - [SAML](development/internal_documentation/saml.md)
-      - [CAS](development/cas.md)
+      - [CAS](development/internal_documentation/cas.md)
-    - [Room DAG concepts](development/room-dag-concepts.md)
+    - [Room DAG concepts](development/internal_documentation/room-dag-concepts.md)
     - [State Resolution]()
-      - [The Auth Chain Difference Algorithm](auth_chain_difference_algorithm.md)
+      - [The Auth Chain Difference Algorithm](development/internal_documentation/auth_chain_difference_algorithm.md)
-    - [Media Repository](media_repository.md)
+    - [Media Repository](development/internal_documentation/media_repository.md)
-    - [Room and User Statistics](room_and_user_statistics.md)
+    - [Room and User Statistics](development/internal_documentation/room_and_user_statistics.md)
   - [Scripts]()
 
 # Other
-  - [Dependency Deprecation Policy](deprecation_policy.md)
+  - [Dependency Deprecation Policy](other/deprecation_policy.md)
   - [Running Synapse on a Single-Board Computer](other/running_synapse_on_single_board_computers.md)

docs/administration/admin_api/README.md

@@ -7,7 +7,11 @@ server admin. (Note that a server admin is distinct from a room admin.)
 
 An existing user can be marked as a server admin by updating the database directly.
 
-Check your [database settings](config_documentation.md#database) in the configuration file, connect to the correct database using either `psql [database name]` (if using PostgreSQL) or `sqlite3 path/to/your/database.db` (if using SQLite) and elevate the user `@foo:bar.com` to administrator.
+Check your [database settings](../../usage/configuration/config_documentation.md#database)
+in the configuration file, connect to the correct database using either 
+`psql [database name]` (if using PostgreSQL) or 
+`sqlite3 path/to/your/database.db` (if using SQLite) and elevate the user 
+`@foo:bar.com` to administrator.
 ```sql
 UPDATE users SET admin = 1 WHERE name = '@foo:bar.com';
 ```
@@ -19,7 +23,7 @@ already on your `$PATH` depending on how Synapse was installed.
 Finding your user's `access_token` is client-dependent, but will usually be shown in the client's settings.
 
 ## Making an Admin API request
-For security reasons, we [recommend](reverse_proxy.md#synapse-administration-endpoints)
+For security reasons, we [recommend](../../setup/reverse_proxy.md#synapse-administration-endpoints)
 that the Admin API (`/_synapse/admin/...`) should be hidden from public view using a
 reverse proxy. This means you should typically query the Admin API from a terminal on
 the machine which runs Synapse.
@@ -35,7 +39,7 @@ For example, suppose we want to
 [query the account](user_admin_api.md#query-user-account) of the user
 `@foo:bar.com`. We need an admin access token (e.g.
 `syt_AjfVef2_L33JNpafeif_0feKJfeaf0CQpoZk`), and we need to know which port
-Synapse's [`client` listener](config_documentation.md#listeners) is listening
+Synapse's [`client` listener](../../usage/configuration/config_documentation.md#listeners) is listening
 on (e.g. `8008`). Then we can use the following command to request the account
 information from the Admin API.
 

docs/administration/admin_api/account_validity.md

@@ -5,7 +5,7 @@ use it, you must enable the account validity feature (under
 `account_validity`) in Synapse's configuration.
 
 To use it, you will need to authenticate by providing an `access_token`
-for a server admin: see [Admin API](../usage/administration/admin_api).
+for a server admin: see [Admin API](index.html).
 
 ## Renew account
 

docs/administration/admin_api/background_updates.md

@@ -106,4 +106,4 @@ The following JSON body parameters are available:
 
 - `job_name` - A string which job to run. Valid values are:
   - `populate_stats_process_rooms` - Recalculate the stats for all rooms.
-  - `regenerate_directory` - Recalculate the [user directory](../../../user_directory.md) if it is stale or out of sync.
+  - `regenerate_directory` - Recalculate the [user directory](../../usage/configuration/user_directory.md) if it is stale or out of sync.

docs/administration/admin_api/event_reports.md

@@ -3,7 +3,7 @@
 This API returns information about reported events.
 
 To use it, you will need to authenticate by providing an `access_token`
-for a server admin: see [Admin API](../usage/administration/admin_api).
+for a server admin: see [Admin API](index.html).
 
 The api is:
 ```

docs/administration/admin_api/federation.md

@@ -81,7 +81,7 @@ The following fields are returned in the JSON response body:
   - `failure_ts` - nullable integer - The first time Synapse tried and failed to reach the
     remote server, in ms. This is `null` if communication with the remote server has never failed.
   - `last_successful_stream_ordering` - nullable integer - The stream ordering of the most
-    recent successfully-sent [PDU](understanding_synapse_through_grafana_graphs.md#federation)
+    recent successfully-sent [PDU](../understanding_synapse_through_grafana_graphs.md#federation)
     to this destination, or `null` if this information has not been tracked yet.
 - `next_token`: string representing a positive integer - Indication for pagination. See above.
 - `total` - integer - Total number of destinations.
@@ -174,7 +174,7 @@ The following fields are returned in the JSON response body:
   Room objects contain the following fields:
   - `room_id` - string - The ID of the room.
   - `stream_ordering` - integer -  The stream ordering of the most recent
-    successfully-sent [PDU](understanding_synapse_through_grafana_graphs.md#federation)
+    successfully-sent [PDU](../understanding_synapse_through_grafana_graphs.md#federation)
     to this destination in this room.
 - `next_token`: string representing a positive integer - Indication for pagination. See above.
 - `total` - integer - Total number of destinations.

docs/administration/admin_api/media_admin_api.md

@@ -3,10 +3,10 @@
 These APIs allow extracting media information from the homeserver.
 
 Details about the format of the `media_id` and storage of the media in the file system
-are documented under [media repository](../media_repository.md).
+are documented under [media repository](../../development/internal_documentation/media_repository.md).
 
 To use it, you will need to authenticate by providing an `access_token`
-for a server admin: see [Admin API](../usage/administration/admin_api).
+for a server admin: see [Admin API](index.html).
 
 ## List all media in a room
 

docs/administration/admin_api/purge_history_api.md

@@ -11,7 +11,7 @@ Note that Synapse requires at least one message in each room, so it will never
 delete the last message in a room.
 
 To use it, you will need to authenticate by providing an `access_token`
-for a server admin: see [Admin API](../usage/administration/admin_api).
+for a server admin: see [Admin API](index.html).
 
 The API is:
 

docs/administration/admin_api/register_api.md

@@ -5,7 +5,7 @@ non-interactive way. This is generally used for bootstrapping a Synapse
 instance with administrator accounts.
 
 To authenticate yourself to the server, you will need both the shared secret
-([`registration_shared_secret`](../usage/configuration/config_documentation.md#registration_shared_secret)
+([`registration_shared_secret`](../../usage/configuration/config_documentation.md#registration_shared_secret)
 in the homeserver configuration), and a one-time nonce. If the registration
 shared secret is not configured, this API is not enabled.
 

docs/administration/admin_api/registration_tokens.md

@@ -6,7 +6,7 @@ registration requests, as proposed in
 and stabilised in version 1.2 of the Matrix specification.
 To use it, you will need to enable the `registration_requires_token` config
 option, and authenticate by providing an `access_token` for a server admin:
-see [Admin API](../admin_api).
+see [Admin API](index.html).
 
 
 ## Registration token objects

docs/administration/admin_api/room_membership.md

@@ -6,7 +6,7 @@ local users. The server administrator must be in the room and have permission to
 invite users.
 
 To use it, you will need to authenticate by providing an `access_token`
-for a server admin: see [Admin API](../usage/administration/admin_api).
+for a server admin: see [Admin API](index.html).
 
 ## Parameters
 

docs/administration/admin_api/rooms.md

@@ -5,7 +5,7 @@ server. There are various parameters available that allow for filtering and
 sorting the returned list. This API supports pagination.
 
 To use it, you will need to authenticate by providing an `access_token`
-for a server admin: see [Admin API](../usage/administration/admin_api).
+for a server admin: see [Admin API](index.html).
 
 **Parameters**
 
@@ -400,7 +400,7 @@ sent to a room in a given timeframe. There are various parameters available
 that allow for filtering and ordering the returned list. This API supports pagination.
 
 To use it, you will need to authenticate by providing an `access_token`
-for a server admin: see [Admin API](../usage/administration/admin_api).
+for a server admin: see [Admin API](index.html).
 
 This endpoint mirrors the [Matrix Spec defined Messages API](https://spec.matrix.org/v1.1/client-server-api/#get_matrixclientv3roomsroomidmessages).
 

docs/administration/admin_api/server_notices.md

@@ -45,4 +45,4 @@ Once the notice has been sent, the API will return the following response:
 ```
 
 Note that server notices must be enabled in `homeserver.yaml` before this API
-can be used. See [the server notices documentation](../server_notices.md) for more information.
+can be used. See [the server notices documentation](../../usage/configuration/server_notices.md) for more information.

docs/administration/admin_api/statistics.md

@@ -4,7 +4,7 @@ Returns information about all local media usage of users. Gives the
 possibility to filter them by time and user.
 
 To use it, you will need to authenticate by providing an `access_token`
-for a server admin: see [Admin API](../usage/administration/admin_api).
+for a server admin: see [Admin API](index.html).
 
 The API is:
 

docs/administration/admin_api/user_admin_api.md

@@ -1,7 +1,7 @@
 # User Admin API
 
 To use it, you will need to authenticate by providing an `access_token`
-for a server admin: see [Admin API](../usage/administration/admin_api).
+for a server admin: see [Admin API](index.html).
 
 ## Query User Account
 
@@ -127,7 +127,7 @@ Body parameters:
   belonging to a user.
 - `external_ids` - array, optional. Allow setting the identifier of the external identity
   provider for SSO (Single sign-on). Details in the configuration manual under the
-  sections [sso](../usage/configuration/config_documentation.md#sso) and [oidc_providers](../usage/configuration/config_documentation.md#oidc_providers).
+  sections [sso](../../usage/configuration/config_documentation.md#sso) and [oidc_providers](../../usage/configuration/config_documentation.md#oidc_providers).
   - `auth_provider` - string. ID of the external identity provider. Value of `idp_id`
     in the homeserver configuration. Note that no error is raised if the provided
     value is not in the homeserver configuration.
@@ -548,9 +548,9 @@ The following fields are returned in the JSON response body:
 ### List media uploaded by a user
 Gets a list of all local media that a specific `user_id` has created.
 These are media that the user has uploaded themselves
-([local media](../media_repository.md#local-media)), as well as
+([local media](../../development/internal_documentation/media_repository.md#local-media)), as well as
-[URL preview images](../media_repository.md#url-previews) requested by the user if the
+[URL preview images](../../development/internal_documentation/media_repository.md#url-previews) requested by the user if the
-[feature is enabled](../usage/configuration/config_documentation.md#url_preview_enabled).
+[feature is enabled](../../usage/configuration/config_documentation.md#url_preview_enabled).
 
 By default, the response is ordered by descending creation date and ascending media ID.
 The newest media is on top. You can change the order with parameters
@@ -650,7 +650,7 @@ The following fields are returned in the JSON response body:
   - `last_access_ts` - integer - Timestamp when the content was last accessed in ms.
   - `media_id` - string - The id used to refer to the media. Details about the format
     are documented under
-    [media repository](../media_repository.md).
+    [media repository](../../development/internal_documentation/media_repository.md).
   - `media_length` - integer - Length of the media in bytes.
   - `media_type` - string - The MIME-type of the media.
   - `quarantined_by` - string - The user ID that initiated the quarantine request

docs/administration/admin_faq.md

@@ -2,7 +2,7 @@
 
 How do I become a server admin?
 ---
-If your server already has an admin account you should use the [User Admin API](../../admin_api/user_admin_api.md#Change-whether-a-user-is-a-server-administrator-or-not) to promote other accounts to become admins.
+If your server already has an admin account you should use the [User Admin API](../../administration/admin_api/user_admin_api.md#Change-whether-a-user-is-a-server-administrator-or-not) to promote other accounts to become admins.
 
 If you don't have any admin accounts yet you won't be able to use the admin API, so you'll have to edit the database manually. Manually editing the database is generally not recommended so once you have an admin account: use the admin APIs to make further changes.
 
@@ -35,7 +35,7 @@ SELECT NAME from users;
 Manually resetting passwords
 ---
 Users can reset their password through their client. Alternatively, a server admin
-can reset a user's password using the [admin API](../../admin_api/user_admin_api.md#reset-password).
+can reset a user's password using the [admin API](../../administration/admin_api/user_admin_api.md#reset-password).
 
 
 I have a problem with my server. Can I just delete my database and start again?
@@ -101,7 +101,7 @@ ORDER BY num_rows desc
 LIMIT 10;
 ```
 
-You can also use the [List Room API](../../admin_api/rooms.md#list-room-api)
+You can also use the [List Room API](../../administration/admin_api/rooms.md#list-room-api)
 and `order_by` `state_events`.
 
 
@@ -115,14 +115,14 @@ something like the following in their logs:
 
     2019-09-11 19:32:04,271 - synapse.federation.transport.server - 288 - WARNING - GET-11752 - authenticate_request failed: 401: Invalid signature for server <server> with key ed25519:a_EqML: Unable to verify signature for <server>
 
-This is normally caused by a misconfiguration in your reverse-proxy. See [the reverse proxy docs](docs/reverse_proxy.md) and double-check that your settings are correct.
+This is normally caused by a misconfiguration in your reverse-proxy. See [the reverse proxy docs](../setup/reverse_proxy.md) and double-check that your settings are correct.
 
 
 Help!! Synapse is slow and eats all my RAM/CPU!
 -----------------------------------------------
 
 First, ensure you are running the latest version of Synapse, using Python 3
-with a [PostgreSQL database](../../postgres.md).
+with a [PostgreSQL database](../setup/postgres.md).
 
 Synapse's architecture is quite RAM hungry currently - we deliberately
 cache a lot of recent room data and metadata in RAM in order to speed up
@@ -157,7 +157,7 @@ massive excess of outgoing federation requests (see [discussion](https://github.
 indicate that your server is also issuing far more outgoing federation
 requests than can be accounted for by your users' activity, this is a
 likely cause. The misbehavior can be worked around by disabling presence
-in the Synapse config file: [see here](../configuration/config_documentation.md#presence).
+in the Synapse config file: [see here](../usage/configuration/config_documentation.md#presence).
 
 
 Running out of File Handles

docs/administration/database_maintenance_tools.md

@@ -2,13 +2,13 @@ This blog post by Victor Berger explains how to use many of the tools listed on
 
 # List of useful tools and scripts for maintenance Synapse database:
 
-## [Purge Remote Media API](../../admin_api/media_admin_api.md#purge-remote-media-api)
+## [Purge Remote Media API](../../administration/admin_api/media_admin_api.md#purge-remote-media-api)
 The purge remote media API allows server admins to purge old cached remote media.
 
-## [Purge Local Media API](../../admin_api/media_admin_api.md#delete-local-media)
+## [Purge Local Media API](../../administration/admin_api/media_admin_api.md#delete-local-media)
 This API deletes the *local* media from the disk of your own server.
 
-## [Purge History API](../../admin_api/purge_history_api.md)
+## [Purge History API](../../administration/admin_api/purge_history_api.md)
 The purge history API allows server admins to purge historic events from their database, reclaiming disk space.
 
 ## [synapse-compress-state](https://github.com/matrix-org/rust-synapse-compress-state)

docs/administration/manhole.md

@@ -15,7 +15,7 @@ environments where untrusted users have shell access.
 
 To enable it, first add the `manhole` listener configuration in your
 `homeserver.yaml`. You can find information on how to do that 
-in the [configuration manual](usage/configuration/config_documentation.md#manhole_settings).
+in the [configuration manual](../usage/configuration/config_documentation.md#manhole_settings).
 The configuration is slightly different if you're using docker.
 
 #### Docker config

docs/administration/metrics-howto.md

@@ -92,7 +92,7 @@
 
 ## Monitoring workers
 
-To monitor a Synapse installation using [workers](workers.md),
+To monitor a Synapse installation using [workers](../usage/configuration/workers.md),
 every worker needs to be monitored independently, in addition to
 the main homeserver process. This is because workers don't send
 their metrics to the main homeserver process, but expose them

docs/administration/monthly_active_users.md

@@ -3,11 +3,11 @@
 Synapse can be configured to record the number of monthly active users (also referred to as MAU) on a given homeserver.
 For clarity's sake, MAU only tracks local users.
 
-Please note that the metrics recorded by the [Homeserver Usage Stats](../../usage/administration/monitoring/reporting_homeserver_usage_statistics.md)
+Please note that the metrics recorded by the [Homeserver Usage Stats](reporting_homeserver_usage_statistics.md)
 are calculated differently. The `monthly_active_users` from the usage stats does not take into account any
 of the rules below, and counts any users who have made a request to the homeserver in the last 30 days.
 
-See the [configuration manual](../../usage/configuration/config_documentation.md#limit_usage_by_mau) for details on how to configure MAU.
+See the [configuration manual](../usage/configuration/config_documentation.md#limit_usage_by_mau) for details on how to configure MAU.
 
 ## Calculating active users
 

docs/administration/reporting_homeserver_usage_statistics.md

@@ -6,9 +6,9 @@ provide the foundation a glimpse into the number of Synapse homeservers
 participating in the network, as well as statistics such as the number of
 rooms being created and messages being sent. This feature is sometimes
 affectionately called "phone home" stats. Reporting
-[is optional](../../configuration/config_documentation.md#report_stats)
+[is optional](../usage/configuration/config_documentation.md#report_stats)
 and the reporting endpoint
-[can be configured](../../configuration/config_documentation.md#report_stats_endpoint),
+[can be configured](../usage/configuration/config_documentation.md#report_stats_endpoint),
 in case you would like to instead report statistics from a set of homeservers
 to your own infrastructure.
 
@@ -52,15 +52,15 @@ The following statistics are sent to the configured reporting endpoint:
 | `r30v2_users_ios`          | int    | The number of 30 day retained users, as defined above. Filtered only to clients with ("riot" or "element") and "ios" (case-insensitive) in the user agent string.                                                                                                                               |
 | `r30v2_users_electron`     | int    | The number of 30 day retained users, as defined above. Filtered only to clients with ("riot" or "element") and "electron" (case-insensitive) in the user agent string.                                                                                                                          |
 | `r30v2_users_web`          | int    | The number of 30 day retained users, as defined above. Filtered only to clients with "mozilla" or "gecko" (case-insensitive) in the user agent string.                                                                                                                                          |
-| `cache_factor`             | int    | The configured [`global factor`](../../configuration/config_documentation.md#caching) value for caching.                                                                                                                                                                                        |
+| `cache_factor`             | int    | The configured [`global factor`](../usage/configuration/config_documentation.md#caching) value for caching.                                                                                                                                                                                        |
-| `event_cache_size`         | int    | The configured [`event_cache_size`](../../configuration/config_documentation.md#caching) value for caching.                                                                                                                                                                                     |
+| `event_cache_size`         | int    | The configured [`event_cache_size`](../usage/configuration/config_documentation.md#caching) value for caching.                                                                                                                                                                                     |
 | `database_engine`          | string | The database engine that is in use. Either "psycopg2" meaning PostgreSQL is in use, or "sqlite3" for SQLite3.                                                                                                                                                                                   |
 | `database_server_version` | string | The version of the database server. Examples being "10.10" for PostgreSQL server version 10.0, and "3.38.5" for SQLite 3.38.5 installed on the system.                                                                                                                                          |
 | `log_level` | string | The log level in use. Examples are "INFO", "WARNING", "ERROR", "DEBUG", etc.                                                                                                                                                                                                                    |
 
 
 [^1]: Native matrix users and guests are always counted. If the
-[`track_puppeted_user_ips`](../../configuration/config_documentation.md#track_puppeted_user_ips)
+[`track_puppeted_user_ips`](../usage/configuration/config_documentation.md#track_puppeted_user_ips)
 option is set to `true`, "puppeted" users (users that an Application Service have performed
 [an action on behalf of](https://spec.matrix.org/v1.3/application-service-api/#identity-assertion))
 will also be counted. Note that an Application Service can "puppet" any user in their
@@ -71,7 +71,7 @@ will additionally be counted as a user (irrespective of `track_puppeted_user_ips
 ## Using a Custom Statistics Collection Server
 
 If statistics reporting is enabled, the endpoint that Synapse sends metrics to is configured by the
-[`report_stats_endpoint`](../../configuration/config_documentation.md#report_stats_endpoint) config
+[`report_stats_endpoint`](../usage/configuration/config_documentation.md#report_stats_endpoint) config
 option. By default, statistics are sent to Matrix.org.
 
 If you would like to set up your own statistics collection server and send metrics there, you may

docs/administration/request_log.md

@@ -1,6 +1,6 @@
 # Request log format
 
-HTTP request logs are written by synapse (see [`site.py`](../synapse/http/site.py) for details).
+HTTP request logs are written by synapse (see [`site.py`](https://github.com/matrix-org/synapse/blob/latest/synapse/http/site.py) for details).
 
 See the following for how to decode the dense data available from the default logging configuration.
 

docs/administration/understanding_synapse_through_grafana_graphs.md

@@ -2,7 +2,7 @@
 
 It is possible to monitor much of the internal state of Synapse using [Prometheus](https://prometheus.io) 
 metrics and [Grafana](https://grafana.com/). 
-A guide for configuring Synapse to provide metrics is available [here](../../metrics-howto.md) 
+A guide for configuring Synapse to provide metrics is available [here](../../administration/metrics-howto.md) 
 and information on setting up Grafana is [here](https://github.com/matrix-org/synapse/tree/master/contrib/grafana).
 In this setup, Prometheus will periodically scrape the information Synapse provides and
 store a record of it over time. Grafana is then used as an interface to query and
@@ -79,6 +79,6 @@ indicator of problems, and a symptom of other problems though, so check other gr
 
 If you're still having performance problems with your Synapse instance and you've 
 tried everything you can, it may just be a lack of system resources. Consider adding
-more CPU and RAM, and make use of [worker mode](../../workers.md) 
+more CPU and RAM, and make use of [worker mode](../usage/configuration/workers.md) 
 to make use of multiple CPU cores / multiple machines for your homeserver.
 

docs/development/code_style.md

@@ -75,7 +75,7 @@ on save as they take a while and can be very resource intensive.
 When adding a configuration option to the code, if several settings are grouped into a single dict, ensure that your code
 correctly handles the top-level option being set to `None` (as it will be if no sub-options are enabled).
 
-The [configuration manual](usage/configuration/config_documentation.md) acts as a
+The [configuration manual](../usage/configuration/config_documentation.md) acts as a
 reference to Synapse's configuration options for server administrators.
 Remember that many readers will be unfamiliar with YAML and server
 administration in general, so it is important that when you add

docs/development/contributing_guide.md

@@ -103,9 +103,9 @@ Synapse developers.
 regarding Synapse's Admin API, which is used mostly by sysadmins and external
 service developers.
 
-Synapse's code style is documented [here](../code_style.md). Please follow
+Synapse's code style is documented [here](code_style.md). Please follow
 it, including the conventions for the [sample configuration
-file](../code_style.md#configuration-file-format).
+file](code_style.md#configuration-file-format).
 
 We welcome improvements and additions to our documentation itself! When
 writing new pages, please

docs/development/opentracing.md

@@ -58,7 +58,7 @@ https://www.jaegertracing.io/docs/latest/getting-started.
 
 OpenTracing is not enabled by default. It must be enabled in the
 homeserver config by adding the `opentracing` option to your config file. You can find 
-documentation about how to do this in the [config manual under the header 'Opentracing'](usage/configuration/config_documentation.md#opentracing).
+documentation about how to do this in the [config manual under the header 'Opentracing'](../usage/configuration/config_documentation.md#opentracing).
 See below for an example Opentracing configuration: 
 
 ```yaml

docs/other/running_synapse_on_single_board_computers.md

@@ -20,7 +20,7 @@ Joining a "large", federated room will initially fail with the below message in
 
 ![Screenshot_2020-10-02_17-15-06](https://user-images.githubusercontent.com/71895/94945781-18771500-04d3-11eb-8419-83c2da73a341.png)
 
-This is [#1211](https://github.com/matrix-org/synapse/issues/1211) and will also hopefully be mitigated by peeking [matrix-org/matrix-doc#2753](https://github.com/matrix-org/matrix-doc/pull/2753) so at least you don't need to wait for a join to complete before finding out if it's the kind of room you want. Note that you should first disable presence, otherwise it'll just make the situation worse [#3120](https://github.com/matrix-org/synapse/issues/3120). There is a lot of database interaction too, so make sure you've [migrated your data](../postgres.md) from the default sqlite to postgresql. Personally, I recommend patience - once the initial join is complete there's rarely any issues with actually interacting with the room, but if you like you can just block "large" rooms entirely.
+This is [#1211](https://github.com/matrix-org/synapse/issues/1211) and will also hopefully be mitigated by peeking [matrix-org/matrix-doc#2753](https://github.com/matrix-org/matrix-doc/pull/2753) so at least you don't need to wait for a join to complete before finding out if it's the kind of room you want. Note that you should first disable presence, otherwise it'll just make the situation worse [#3120](https://github.com/matrix-org/synapse/issues/3120). There is a lot of database interaction too, so make sure you've [migrated your data](../setup/postgres.md) from the default sqlite to postgresql. Personally, I recommend patience - once the initial join is complete there's rarely any issues with actually interacting with the room, but if you like you can just block "large" rooms entirely.
 
 ### Sessions
 

docs/presence_router_module.md

@@ -36,7 +36,7 @@ presence to (for those users that the receiving user is considered interested in
 It does not include state for users who are currently offline, and it can only be
 called on workers that support sending federation. Additionally, this method must
 only be called from the process that has been configured to write to the
-the [presence stream](workers.md#stream-writers).
+the [presence stream](usage/configuration/workers.md#stream-writers).
 By default, this is the main process, but another worker can be configured to do
 so.
 

docs/setup/installation.md

@@ -14,7 +14,7 @@ production-ready setup, you will probably want to specify your domain
 (`example.com`) rather than a matrix-specific hostname here (in the same way
 that your email address is probably `user@example.com` rather than
 `user@email.example.com`) - but doing so may require more advanced setup: see
-[Setting up Federation](../federate.md).
+[Setting up Federation](../usage/federate.md).
 
 ## Installing Synapse
 
@@ -392,7 +392,7 @@ instead. Advantages include:
 - allowing the DB to be run on separate hardware
 
 For information on how to install and use PostgreSQL in Synapse, please see
-[Using Postgres](../postgres.md)
+[Using Postgres](postgres.md)
 
 SQLite is only acceptable for testing purposes. SQLite should not be used in
 a production server. Synapse will perform poorly when using
@@ -407,7 +407,7 @@ over HTTPS.
 
 The recommended way to do so is to set up a reverse proxy on port
 `8448`. You can find documentation on doing so in
-[the reverse proxy documentation](../reverse_proxy.md).
+[the reverse proxy documentation](reverse_proxy.md).
 
 Alternatively, you can configure Synapse to expose an HTTPS port. To do
 so, you will need to edit `homeserver.yaml`, as follows:
@@ -436,7 +436,7 @@ listeners:
   `cert.pem`).
 
 For a more detailed guide to configuring your server for federation, see
-[Federation](../federate.md).
+[Federation](../usage/federate.md).
 
 ### Client Well-Known URI
 
@@ -553,7 +553,7 @@ it can register users, including admin accounts, on your server even if
 ### Setting up a TURN server
 
 For reliable VoIP calls to be routed via this homeserver, you MUST configure
-a TURN server. See [TURN setup](../turn-howto.md) for details.
+a TURN server. See [TURN setup](turn-howto.md) for details.
 
 ### URL previews
 

docs/setup/postgres.md

@@ -8,14 +8,14 @@ Synapse will require the python postgres client library in order to
 connect to a postgres database.
 
 -   If you are using the [matrix.org debian/ubuntu
-    packages](setup/installation.md#matrixorg-packages), the necessary python
+    packages](installation.md#matrixorg-packages), the necessary python
     library will already be installed, but you will need to ensure the
     low-level postgres library is installed, which you can do with
     `apt install libpq5`.
 -   For other pre-built packages, please consult the documentation from
     the relevant package.
 -   If you installed synapse [in a
-    virtualenv](setup/installation.md#installing-from-source), you can install
+    virtualenv](installation.md#installing-from-source), you can install
     the library with:
 
         ~/synapse/env/bin/pip install "matrix-synapse[postgres]"

docs/upgrade.md

@@ -204,7 +204,7 @@ which relays replication commands between processes. This can give a significant
 CPU saving on the main process and is a prerequisite for upcoming
 performance improvements.
 
-To migrate to Redis add the [`redis` config](./workers.md#shared-configuration),
+To migrate to Redis add the [`redis` config](usage/configuration/workers.md#shared-configuration),
 and remove the TCP `replication` listener from config of the master and
 `worker_replication_port` from worker config. Note that a HTTP listener with a
 `replication` resource is still required.
@@ -507,8 +507,8 @@ Please see the [*Notifying Application Services*][v1_59_notify_ases_from] and
 [*Updating the User Directory*][v1_59_update_user_dir] sections of the worker
 documentation for more information.
 
-[v1_59_notify_ases_from]: workers.md#notifying-application-services
+[v1_59_notify_ases_from]: usage/configuration/workers.md#notifying-application-services
-[v1_59_update_user_dir]: workers.md#updating-the-user-directory
+[v1_59_update_user_dir]: usage/configuration/workers.md#updating-the-user-directory
 
 
 # Upgrading to v1.58.0
@@ -726,7 +726,7 @@ will become a configuration error in Synapse v1.53.0.
 
 ## Dropping support for old Python and Postgres versions
 
-In line with our [deprecation policy](deprecation_policy.md),
+In line with our [deprecation policy](other/deprecation_policy.md),
 we've dropped support for Python 3.6 and PostgreSQL 9.6, as they are no
 longer supported upstream.
 
@@ -797,8 +797,8 @@ Any scripts still using the above APIs should be converted to use the
 ## User-interactive authentication fallback templates can now display errors
 
 This may affect you if you make use of custom HTML templates for the
-[reCAPTCHA](../synapse/res/templates/recaptcha.html) or
+[reCAPTCHA](https://github.com/matrix-org/synapse/blob/v1.42.0/synapse/res/templates/recaptcha.html) or
-[terms](../synapse/res/templates/terms.html) fallback pages.
+[terms](https://github.com/matrix-org/synapse/blob/v1.42.0/synapse/res/templates/terms.html) fallback pages.
 
 The template is now provided an `error` variable if the authentication
 process failed. See the default templates linked above for an example.
@@ -983,7 +983,7 @@ Instructions for doing so are provided
 
 ## Dropping support for old Python, Postgres and SQLite versions
 
-In line with our [deprecation policy](deprecation_policy.md),
+In line with our [deprecation policy](other/deprecation_policy.md),
 we've dropped support for Python 3.5 and PostgreSQL 9.5, as they are no
 longer supported upstream.
 
@@ -996,7 +996,7 @@ The deprecated v1 "list accounts" admin API
 (`GET /_synapse/admin/v1/users/<user_id>`) has been removed in this
 version.
 
-The [v2 list accounts API](admin_api/user_admin_api.md#list-accounts)
+The [v2 list accounts API](administration/admin_api/user_admin_api.md#list-accounts)
 has been available since Synapse 1.7.0 (2019-12-13), and is accessible
 under `GET /_synapse/admin/v2/users`.
 
@@ -1031,7 +1031,7 @@ by the client.
 
 Synapse also requires the `Host` header to be preserved.
 
-See the [reverse proxy documentation](reverse_proxy.md), where the
+See the [reverse proxy documentation](setup/reverse_proxy.md), where the
 example configurations have been updated to show how to set these
 headers.
 
@@ -1050,7 +1050,7 @@ identity providers:
     `[synapse public baseurl]/_synapse/client/oidc/callback` to the list
     of permitted "redirect URIs" at the identity provider.
 
-    See the [OpenID docs](openid.md) for more information on setting
+    See the [OpenID docs](usage/configuration/user_authentication/single_sign_on/openid.md) for more information on setting
     up OpenID Connect.
 
 -   If your server is configured for single sign-on via a SAML2 identity
@@ -1280,13 +1280,13 @@ acts the same as the `http_client` argument previously passed to
 
 ## Forwarding `/_synapse/client` through your reverse proxy
 
-The [reverse proxy documentation](reverse_proxy.md)
+The [reverse proxy documentation](setup/reverse_proxy.md)
 has been updated to include reverse proxy directives for
 `/_synapse/client/*` endpoints. As the user password reset flow now uses
 endpoints under this prefix, **you must update your reverse proxy
 configurations for user password reset to work**.
 
-Additionally, note that the [Synapse worker documentation](workers.md) has been updated to
+Additionally, note that the [Synapse worker documentation](usage/configuration/workers.md) has been updated to
 
 :   state that the `/_synapse/client/password_reset/email/submit_token`
     endpoint can be handled
@@ -1396,7 +1396,7 @@ New templates (`sso_auth_confirm.html`, `sso_auth_success.html`, and
 is configured to use SSO and a custom
 `sso_redirect_confirm_template_dir` configuration then these templates
 will need to be copied from
-[synapse/res/templates](synapse/res/templates) into that directory.
+[synapse/res/templates](https://github.com/matrix-org/synapse/tree/v1.13/synapse/res/templates) into that directory.
 
 ## Synapse SSO Plugins Method Deprecation
 
@@ -1482,7 +1482,7 @@ participating in many rooms.
     omitting the `CONCURRENTLY` keyword. Note however that this
     operation may in itself cause Synapse to stop running for some time.
     Synapse admins are reminded that [SQLite is not recommended for use
-    outside a test environment](postgres.md).
+    outside a test environment](setup/postgres.md).
 
 3.  Once the index has been created, the `SELECT` query in step 1 above
     should complete quickly. It is therefore safe to upgrade to Synapse
@@ -1500,7 +1500,7 @@ participating in many rooms.
 Synapse will now log a warning on start up if used with a PostgreSQL
 database that has a non-recommended locale set.
 
-See [Postgres](postgres.md) for details.
+See [Postgres](setup/postgres.md) for details.
 
 # Upgrading to v1.8.0
 
@@ -1720,7 +1720,7 @@ back to v1.3.1, subject to the following:
 
 Some counter metrics have been renamed, with the old names deprecated.
 See [the metrics
-documentation](metrics-howto.md#renaming-of-metrics--deprecation-of-old-names-in-12)
+documentation](administration/metrics-howto.md#renaming-of-metrics--deprecation-of-old-names-in-12)
 for details.
 
 # Upgrading to v1.1.0

docs/usage/configuration/config_documentation.md

@@ -115,7 +115,7 @@ usernames on your server would be in the format `@user:example.com`
 In most cases you should avoid using a matrix specific subdomain such as
 matrix.example.com or synapse.example.com as the `server_name` for the same
 reasons you wouldn't use user@email.example.com as your email address.
-See [here](../../delegate.md)
+See [here](../../setup/delegate.md)
 for information on how to host Synapse on a subdomain while preserving
 a clean `server_name`.
 
@@ -179,7 +179,7 @@ This will tell other servers to send traffic to port 443 instead.
 
 This option currently defaults to false.
 
-See [Delegation of incoming federation traffic](../../delegate.md) for more
+See [Delegation of incoming federation traffic](../../setup/delegate.md) for more
 information.
 
 Example configuration:
@@ -427,21 +427,21 @@ Sub-options for each listener include:
 
 * `type`: the type of listener. Normally `http`, but other valid options are:
 
-   * `manhole`: (see the docs [here](../../manhole.md)),
+   * `manhole`: (see the docs [here](../../administration/manhole.md)),
 
-   * `metrics`: (see the docs [here](../../metrics-howto.md)),
+   * `metrics`: (see the docs [here](../../administration/metrics-howto.md)),
 
 * `tls`: set to true to enable TLS for this listener. Will use the TLS key/cert specified in tls_private_key_path / tls_certificate_path.
 
 * `x_forwarded`: Only valid for an 'http' listener. Set to true to use the X-Forwarded-For header as the client IP. Useful when Synapse is
-   behind a [reverse-proxy](../../reverse_proxy.md).
+   behind a [reverse-proxy](../../setup/reverse_proxy.md).
 
 * `request_id_header`: The header extracted from each incoming request that is
    used as the basis for the request ID. The request ID is used in
-   [logs](../administration/request_log.md#request-log-format) and tracing to
+   [logs](../../administration/request_log.md#request-log-format) and tracing to
    correlate and match up requests. When unset, Synapse will automatically
    generate sequential request IDs. This option is useful when Synapse is behind
-   a [reverse-proxy](../../reverse_proxy.md).
+   a [reverse-proxy](../../setup/reverse_proxy.md).
 
    _Added in Synapse 1.68.0._
 
@@ -460,7 +460,7 @@ Valid resource names are:
 
 * `client`: the client-server API (/_matrix/client), and the synapse admin API (/_synapse/admin). Also implies `media` and `static`.
 
-* `consent`: user consent forms (/_matrix/consent). See [here](../../consent_tracking.md) for more.
+* `consent`: user consent forms (/_matrix/consent). See [here](consent_tracking.md) for more.
 
 * `federation`: the server-server API (/_matrix/federation). Also implies `media`, `keys`, `openid`
 
@@ -468,11 +468,11 @@ Valid resource names are:
 
 * `media`: the media API (/_matrix/media).
 
-* `metrics`: the metrics interface. See [here](../../metrics-howto.md).
+* `metrics`: the metrics interface. See [here](../../administration/metrics-howto.md).
 
-* `openid`: OpenID authentication. See [here](../../openid.md).
+* `openid`: OpenID authentication. See [here](user_authentication/single_sign_on/openid.md).
 
-* `replication`: the HTTP replication API (/_synapse/replication). See [here](../../workers.md).
+* `replication`: the HTTP replication API (/_synapse/replication). See [here](workers.md).
 
 * `static`: static resources under synapse/static (/_matrix/static). (Mostly useful for 'fallback authentication'.)
 
@@ -525,7 +525,7 @@ listeners:
 ### `manhole_settings`
 
 Connection settings for the manhole. You can find more information
-on the manhole [here](../../manhole.md). Manhole sub-options include:
+on the manhole [here](../../administration/manhole.md). Manhole sub-options include:
 * `username` : the username for the manhole. This defaults to 'matrix'.
 * `password`: The password for the manhole. This defaults to 'rabbithole'.
 * `ssh_priv_key_path` and `ssh_pub_key_path`: The private and public SSH key pair used to encrypt the manhole traffic.
@@ -602,7 +602,7 @@ server owner wants to limit to the number of monthly active users. When enabled
 reached the server returns a `ResourceLimitError` with error type `Codes.RESOURCE_LIMIT_EXCEEDED`.
 Defaults to false. If this is enabled, a value for `max_mau_value` must also be set.
 
-See [Monthly Active Users](../administration/monthly_active_users.md) for details on how to configure MAU.
+See [Monthly Active Users](../../administration/monthly_active_users.md) for details on how to configure MAU.
 
 Example configuration:
 ```yaml
@@ -835,7 +835,7 @@ find template files in to use to generate email or HTML page contents.
 If not set, or a file is not found within the template directory, a default
 template from within the Synapse package will be used.
 
-See [here](../../templates.md) for more
+See [here](templates.md) for more
 information about using custom templates.
 
 Example configuration:
@@ -862,7 +862,7 @@ The message retention policies feature is disabled by default. Please be advised
 that enabling this feature carries some risk. There are known bugs with the implementation
 which can cause database corruption. Setting retention to delete older history
 is less risky than deleting newer history but in general caution is advised when enabling this
-experimental feature. You can read more about this feature [here](../../message_retention_policies.md).
+experimental feature. You can read more about this feature [here](message_retention_policies.md).
 
 This setting has the following sub-options:
 * `default_policy`: Default retention policy. If set, Synapse will apply it to rooms that lack the
@@ -1139,7 +1139,7 @@ number of entries that can be stored.
 
 * `cache_autotuning` and its sub-options `max_cache_memory_usage`, `target_cache_memory_usage`, and
    `min_cache_ttl` work in conjunction with each other to maintain a balance between cache memory
-   usage and cache entry availability. You must be using [jemalloc](../administration/admin_faq.md#help-synapse-is-slow-and-eats-all-my-ramcpu)
+   usage and cache entry availability. You must be using [jemalloc](../../administration/admin_faq.md#help-synapse-is-slow-and-eats-all-my-ramcpu)
    to utilize this option, and all three of the options must be specified for this feature to work. This option
    defaults to off, enable it by providing values for the sub-options listed below. Please note that the feature will not work
    and may cause unstable behavior (such as excessive emptying of caches or exceptions) if all of the values are not provided.
@@ -1205,7 +1205,7 @@ Associated sub-options:
 * `allow_unsafe_locale` is an option specific to Postgres. Under the default behavior, Synapse will refuse to
   start if the postgres db is set to a non-C locale. You can override this behavior (which is *not* recommended)
   by setting `allow_unsafe_locale` to true. Note that doing so may corrupt your database. You can find more information
-  [here](../../postgres.md#fixing-incorrect-collate-or-ctype) and [here](https://wiki.postgresql.org/wiki/Locale_data_changes).
+  [here](../../setup/postgres.md#fixing-incorrect-collate-or-ctype) and [here](https://wiki.postgresql.org/wiki/Locale_data_changes).
 
 * `args` gives options which are passed through to the database engine,
   except for options starting with `cp_`, which are used to configure the Twisted
@@ -1215,7 +1215,7 @@ Associated sub-options:
     * for [the connection pool](https://twistedmatrix.com/documents/current/api/twisted.enterprise.adbapi.ConnectionPool.html#__init__)
 
 For more information on using Synapse with Postgres,
-see [here](../../postgres.md).
+see [here](../../setup/postgres.md).
 
 Example SQLite configuration:
 ```yaml
@@ -1626,7 +1626,7 @@ The largest allowed upload size in bytes.
 
 If you are using a reverse proxy you may also need to set this value in
 your reverse proxy's config. Defaults to 50M. Notably Nginx has a small max body size by default.
-See [here](../../reverse_proxy.md) for more on using a reverse proxy with Synapse.
+See [here](../../setup/reverse_proxy.md) for more on using a reverse proxy with Synapse.
 
 Example configuration:
 ```yaml
@@ -1702,9 +1702,9 @@ and the original media will be removed. If either of these options are unset,
 then media of that type will not be purged.
 
 Local or cached remote media that has been
-[quarantined](../../admin_api/media_admin_api.md#quarantining-media-in-a-room)
+[quarantined](../../administration/admin_api/media_admin_api.md#quarantining-media-in-a-room)
 will not be deleted. Similarly, local media that has been marked as
-[protected from quarantine](../../admin_api/media_admin_api.md#protecting-media-from-being-quarantined)
+[protected from quarantine](../../administration/admin_api/media_admin_api.md#protecting-media-from-being-quarantined)
 will not be deleted.
 
 Example configuration:
@@ -1879,7 +1879,7 @@ oembed:
 ---
 ## Captcha ##
 
-See [here](../../CAPTCHA_SETUP.md) for full details on setting up captcha.
+See [here](CAPTCHA_SETUP.md) for full details on setting up captcha.
 
 ---
 ### `recaptcha_public_key`
@@ -2068,7 +2068,7 @@ enable_3pid_lookup: false
 ### `registration_requires_token`
 
 Require users to submit a token during registration.
-Tokens can be managed using the admin [API](../administration/admin_api/registration_tokens.md).
+Tokens can be managed using the admin [API](../../administration/admin_api/registration_tokens.md).
 Disabling this option will not delete any tokens previously generated.
 Defaults to `false`. Set to `true` to enable.
 
@@ -2088,7 +2088,7 @@ set.
 
 This is primarily intended for use with the `register_new_matrix_user` script
 (see [Registering a user](../../setup/installation.md#registering-a-user));
-however, the interface is [documented](../../admin_api/register_api.html).
+however, the interface is [documented](../../administration/admin_api/register_api.md).
 
 See also [`registration_shared_secret_path`](#registration_shared_secret_path).
 
@@ -2498,7 +2498,7 @@ metrics_flags:
 Whether or not to report homeserver usage statistics. This is originally
 set when generating the config. Set this option to true or false to change the current
 behavior. See
-[Reporting Homeserver Usage Statistics](../administration/monitoring/reporting_homeserver_usage_statistics.md)
+[Reporting Homeserver Usage Statistics](../../administration/reporting_homeserver_usage_statistics.md)
 for information on what data is reported.
 
 Statistics will be reported 5 minutes after Synapse starts, and then every 3 hours
@@ -2879,7 +2879,7 @@ saml2_config:
 ### `oidc_providers`
 
 List of OpenID Connect (OIDC) / OAuth 2.0 identity providers, for registration
-and login. See [here](../../openid.md)
+and login. See [here](user_authentication/single_sign_on/openid.md)
 for information on how to configure these options.
 
 For backwards compatibility, it is also possible to configure a single OIDC
@@ -2977,7 +2977,7 @@ Options for each entry include:
 
      * `module`: The class name of a custom mapping module. Default is
        `synapse.handlers.oidc.JinjaOidcMappingProvider`.
-        See [OpenID Mapping Providers](../../sso_mapping_providers.md#openid-mapping-providers)
+        See [OpenID Mapping Providers](user_authentication/single_sign_on/sso_mapping_providers.md#openid-mapping-providers)
         for information on implementing a custom mapping provider.
 
      * `config`: Configuration for the mapping provider module. This section will
@@ -3096,7 +3096,7 @@ Additional settings to use with single-sign on systems such as OpenID Connect,
 SAML2 and CAS.
 
 Server admins can configure custom templates for pages related to SSO. See
-[here](../../templates.md) for more information.
+[here](templates.md) for more information.
 
 Options include:
 * `client_whitelist`: A list of client URLs which are whitelisted so that the user does not
@@ -3142,7 +3142,7 @@ and issued at ("iat") claims are validated if present.
 Note that this is a non-standard login type and client support is
 expected to be non-existent.
 
-See [here](../../jwt.md) for more.
+See [here](user_authentication/jwt.md) for more.
 
 Additional sub-options for this setting include:
 * `enabled`: Set to true to enable authorization using JSON web
@@ -3245,7 +3245,7 @@ ui_auth:
 Configuration for sending emails from Synapse.
 
 Server admins can configure custom templates for email content. See
-[here](../../templates.md) for more information.
+[here](templates.md) for more information.
 
 This setting has the following sub-options:
 * `smtp_host`: The hostname of the outgoing SMTP server to use. Defaults to 'localhost'.
@@ -3425,7 +3425,7 @@ This option has the following sub-options:
     
     These indexes are built the first time Synapse starts; admins can
     manually trigger a rebuild via the API following the instructions
-    [for running background updates](../administration/admin_api/background_updates.md#run),
+    [for running background updates](../../administration/admin_api/background_updates.md#run),
     set to true to return search results containing all known users, even if that
     user does not share a room with the requester.
 * `prefer_local_users`: Defines whether to prefer local users in search query results.
@@ -3442,7 +3442,7 @@ user_directory:
 ---
 ### `user_consent`
 
-For detailed instructions on user consent configuration, see [here](../../consent_tracking.md).
+For detailed instructions on user consent configuration, see [here](consent_tracking.md).
 
 Parts of this section are required if enabling the `consent` resource under
 [`listeners`](#listeners), in particular `template_dir` and `version`.
@@ -3493,7 +3493,7 @@ user_consent:
 ---
 ### `stats`
 
-Settings for local room and user statistics collection. See [here](../../room_and_user_statistics.md)
+Settings for local room and user statistics collection. See [here](../../development/internal_documentation/room_and_user_statistics.md)
 for more.
 
 * `enabled`: Set to false to disable room and user statistics. Note that doing
@@ -3642,7 +3642,7 @@ synapse or any other services which support opentracing
 Sub-options include:
 * `enabled`: whether tracing is enabled. Set to true to enable. Disabled by default.
 * `homeserver_whitelist`: The list of homeservers we wish to send and receive span contexts and span baggage.
-   See [here](../../opentracing.md) for more.
+   See [here](../../development/opentracing.md) for more.
    This is a list of regexes which are matched against the `server_name` of the homeserver.
    By default, it is empty, so no servers are matched.
 * `force_tracing_for_users`: # A list of the matrix IDs of users whose requests will always be traced,

docs/usage/configuration/message_retention_policies.md

@@ -52,7 +52,7 @@ clients.
 
 Support for this feature can be enabled and configured by adding a the
 `retention` in the Synapse configuration file (see
-[configuration manual](usage/configuration/config_documentation.md#retention)).
+[configuration manual](config_documentation.md#retention)).
 
 To enable support for message retention policies, set the setting
 `enabled` in this section to `true`.
@@ -88,7 +88,7 @@ expired events from the database. They are only run if support for
 message retention policies is enabled in the server's configuration. If
 no configuration for purge jobs is configured by the server admin,
 Synapse will use a default configuration, which is described here in the
-[configuration manual](usage/configuration/config_documentation.md#retention).
+[configuration manual](config_documentation.md#retention).
 
 Some server admins might want a finer control on when events are removed
 depending on an event's room's policy. This can be done by setting the

docs/usage/configuration/server_notices.md

@@ -58,4 +58,4 @@ displayname and avatar of the Server Notices user.
 ## Sending notices
 
 To send server notices to users you can use the
-[admin_api](admin_api/server_notices.md).
+[admin_api](../../administration/admin_api/server_notices.md).

docs/usage/configuration/user_authentication/jwt.md

@@ -50,7 +50,7 @@ as follows:
   maintainer.
 
 To enable the JSON web token integration, you should then add a `jwt_config` option
-to your configuration file. See the [configuration manual](usage/configuration/config_documentation.md#jwt_config) for some
+to your configuration file. See the [configuration manual](../config_documentation.md#jwt_config) for some
 sample settings.
 
 ## How to test JWT as a developer

docs/usage/configuration/user_authentication/password_auth_providers.md

@@ -1,7 +1,7 @@
 <h2 style="color:red">
 This page of the Synapse documentation is now deprecated. For up to date
 documentation on setting up or writing a password auth provider module, please see
-<a href="modules/index.md">this page</a>.
+<a href="../../../modules/index.md">this page</a>.
 </h2>
 
 # Password auth provider modules

docs/usage/configuration/user_authentication/single_sign_on/openid.md

@@ -46,7 +46,7 @@ as follows:
 
 To enable the OpenID integration, you should then add a section to the `oidc_providers`
 setting in your configuration file.
-See the [configuration manual](usage/configuration/config_documentation.md#oidc_providers) for some sample settings, as well as
+See the [configuration manual](../../config_documentation.md#oidc_providers) for some sample settings, as well as
 the text below for example configurations for specific providers.
 
 ## Sample configs

docs/usage/configuration/user_authentication/single_sign_on/sso_mapping_providers.md

@@ -37,7 +37,7 @@ as Synapse). The Synapse config is then modified to point to the mapping provide
 ## OpenID Mapping Providers
 
 The OpenID mapping provider can be customized by editing the
-[`oidc_providers.user_mapping_provider.module`](usage/configuration/config_documentation.md#oidc_providers)
+[`oidc_providers.user_mapping_provider.module`](../../config_documentation.md#oidc_providers)
 config option.
 
 `oidc_providers.user_mapping_provider.config` allows you to provide custom
@@ -120,7 +120,7 @@ specified in the config. It is located at
 ## SAML Mapping Providers
 
 The SAML mapping provider can be customized by editing the
-[`saml2_config.user_mapping_provider.module`](docs/usage/configuration/config_documentation.md#saml2_config)
+[`saml2_config.user_mapping_provider.module`](../../config_documentation.md#saml2_config)
 config option.
 
 `saml2_config.user_mapping_provider.config` allows you to provide custom

docs/usage/configuration/user_directory.md

@@ -7,7 +7,7 @@ who are present in a publicly viewable room present on the server.
 
 The directory info is stored in various tables, which can (typically after
 DB corruption) get stale or out of sync. If this happens, for now the
-solution to fix it is to use the [admin API](usage/administration/admin_api/background_updates.md#run)
+solution to fix it is to use the [admin API](../../administration/admin_api/background_updates.md#run)
 and execute the job `regenerate_directory`. This should then start a background task to
 flush the current tables and regenerate the directory.
 

docs/usage/configuration/workers.md

@@ -68,7 +68,7 @@ https://hub.docker.com/r/matrixdotorg/synapse/.
 To make effective use of the workers, you will need to configure an HTTP
 reverse-proxy such as nginx or haproxy, which will direct incoming requests to
 the correct worker, or to the main synapse instance. See
-[the reverse proxy documentation](reverse_proxy.md) for information on setting up a reverse
+[the reverse proxy documentation](../../setup/reverse_proxy.md) for information on setting up a reverse
 proxy.
 
 When using workers, each worker process has its own configuration file which
@@ -111,7 +111,7 @@ redis:
     enabled: true
 ```
 
-See the [configuration manual](usage/configuration/config_documentation.html) for the full documentation of each option.
+See the [configuration manual](config_documentation.md) for the full documentation of each option.
 
 Under **no circumstances** should the replication listener be exposed to the
 public internet; replication traffic is:
@@ -128,7 +128,7 @@ In the config file for each worker, you must specify:
  * The HTTP replication endpoint that it should talk to on the main synapse process
    (`worker_replication_host` and `worker_replication_http_port`)
  * If handling HTTP requests, a `worker_listeners` option with an `http`
-   listener, in the same way as the [`listeners`](usage/configuration/config_documentation.md#listeners)
+   listener, in the same way as the [`listeners`](config_documentation.md#listeners)
    option in the shared config.
  * If handling the `^/_matrix/client/v3/keys/upload` endpoint, the HTTP URI for
    the main process (`worker_main_http_uri`).
@@ -153,7 +153,7 @@ Finally, you need to start your worker processes. This can be done with either
 `synctl` or your distribution's preferred service manager such as `systemd`. We
 recommend the use of `systemd` where available: for information on setting up
 `systemd` to start synapse workers, see
-[Systemd with Workers](systemd-with-workers). To use `synctl`, see
+[Systemd with Workers](systemd-with-workers/index.html). To use `synctl`, see
 [Using synctl with Workers](synctl_workers.md).
 
 
@@ -287,7 +287,7 @@ For multiple workers not handling the SSO endpoints properly, see
 [#7530](https://github.com/matrix-org/synapse/issues/7530) and
 [#9427](https://github.com/matrix-org/synapse/issues/9427).
 
-Note that a [HTTP listener](usage/configuration/config_documentation.md#listeners)
+Note that a [HTTP listener](config_documentation.md#listeners)
 with `client` and `federation` `resources` must be configured in the `worker_listeners`
 option in the worker config.
 
@@ -330,7 +330,7 @@ Additionally, the writing of specific streams (such as events) can be moved off
 of the main process to a particular worker.
 
 To enable this, the worker must have a
-[HTTP `replication` listener](usage/configuration/config_documentation.md#listeners) configured,
+[HTTP `replication` listener](config_documentation.md#listeners) configured,
 have a `worker_name` and be listed in the `instance_map` config. The same worker
 can handle multiple streams, but unless otherwise documented, each stream can only
 have a single writer.
@@ -553,7 +553,7 @@ media repository. Note that doing so will prevent the main process from being
 able to handle the above endpoints.
 
 In the `media_repository` worker configuration file, configure the
-[HTTP listener](usage/configuration/config_documentation.md#listeners) to
+[HTTP listener](config_documentation.md#listeners) to
 expose the `media` resource. For example:
 
 ```yaml

docs/usage/federate.md

@@ -14,7 +14,7 @@ you set the `server_name` to match your machine's public DNS hostname.
 
 For this default configuration to work, you will need to listen for TLS
 connections on port 8448. The preferred way to do that is by using a
-reverse proxy: see [the reverse proxy documentation](reverse_proxy.md) for instructions
+reverse proxy: see [the reverse proxy documentation](../setup/reverse_proxy.md) for instructions
 on how to correctly set one up.
 
 In some cases you might not want to run Synapse on the machine that has
@@ -23,7 +23,7 @@ traffic to use a different port than 8448. For example, you might want to
 have your user names look like `@user:example.com`, but you want to run
 Synapse on `synapse.example.com` on port 443. This can be done using
 delegation, which allows an admin to control where federation traffic should
-be sent. See [the delegation documentation](delegate.md) for instructions on how to set this up.
+be sent. See [the delegation documentation](../setup/delegate.md) for instructions on how to set this up.
 
 Once federation has been configured, you should be able to join a room over
 federation. A good place to start is `#synapse:matrix.org` - a room for
@@ -44,7 +44,7 @@ a complicated dance which requires connections in both directions).
 
 Another common problem is that people on other servers can't join rooms that
 you invite them to. This can be caused by an incorrectly-configured reverse
-proxy: see [the reverse proxy documentation](reverse_proxy.md) for instructions on how
+proxy: see [the reverse proxy documentation](../setup/reverse_proxy.md) for instructions on how
 to correctly configure a reverse proxy.
 
 ### Known issues

docs/welcome_and_overview.md

@@ -16,16 +16,16 @@ This documentation covers topics for **installation**, **configuration** and
 * See how to [upgrade](upgrade.md) between Synapse versions.
 
 * Administer your instance using the [Admin
-  API](usage/administration/admin_api/index.html), installing [pluggable
+  API](administration/admin_api/index.html), installing [pluggable
-  modules](modules/index.html), or by accessing the [manhole](manhole.md).
+  modules](modules/index.html), or by accessing the [manhole](administration/manhole.md).
 
-* Learn how to [read log lines](usage/administration/request_log.md), configure
+* Learn how to [read log lines](administration/request_log.md), configure
   [logging](usage/configuration/logging_sample_config.md) or set up [structured
-  logging](structured_logging.md).
+  logging](usage/configuration/structured_logging.md).
 
-* Scale Synapse through additional [worker processes](workers.md).
+* Scale Synapse through additional [worker processes](usage/configuration/workers.md).
 
-* Set up [monitoring and metrics](metrics-howto.md) to keep an eye on your
+* Set up [monitoring and metrics](administration/metrics-howto.md) to keep an eye on your
   Synapse instance's performance.
 
 ## Developing on Synapse
@@ -52,8 +52,8 @@ following documentation:
 * Understand [how Synapse is
   built](development/internal_documentation/index.html), how to [migrate
   database schemas](development/database_schema.md), learn about
-  [federation](federate.md) and how to [set up a local
+  [federation](usage/federate.md) and how to [set up a local
-  federation](federate.md#running-a-demo-federation-of-synapses) for development.
+  federation](usage/federate.md#running-a-demo-federation-of-synapses) for development.
 
 * We like to keep our `git` history clean. [Learn](development/git.md) how to
   do so!