Move config pages into config dir

34 files changed, 52 insertions, 52 deletions

diff --git a/docker/README-testing.md b/docker/README-testing.md
index 21b99963d8..8e218ca832 100644
--- a/docker/README-testing.md
+++ b/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...`).
 
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index ceb96b5c6d..048ee80ff5 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -20,23 +20,23 @@
     - [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)
-    - [Templates](templates.md)
+    - [Structured Logging](usage/configuration/structured_logging.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)
-      - [Password Auth Providers](password_auth_providers.md)
-      - [JSON Web Tokens](jwt.md)
+        - [SSO Mapping Providers](usage/configuration/user_authentication/single_sign_on/sso_mapping_providers.md)
+      - [Password Auth Providers](usage/configuration/user_authentication/password_auth_providers.md)
+      - [JSON Web Tokens](usage/configuration/user_authentication/jwt.md)
       - [Refresh Tokens](usage/configuration/user_authentication/refresh_tokens.md)
-    - [Registration Captcha](CAPTCHA_SETUP.md)
-    - [Application Services](application_services.md)
-    - [Server Notices](server_notices.md)
-    - [Consent Tracking](consent_tracking.md)
-    - [User Directory](user_directory.md)
-    - [Message Retention Policies](message_retention_policies.md)
+    - [Registration Captcha](usage/configuration/CAPTCHA_SETUP.md)
+    - [Application Services](usage/configuration/application_services.md)
+    - [Server Notices](usage/configuration/server_notices.md)
+    - [Consent Tracking](usage/configuration/consent_tracking.md)
+    - [User Directory](usage/configuration/user_directory.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,9 +47,9 @@
         - [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)
-      - [Using `synctl` with Workers](synctl_workers.md)
-      - [Systemd](systemd-with-workers/README.md)
+    - [Workers](usage/configuration/workers.md)
+      - [Using `synctl` with Workers](usage/configuration/synctl_workers.md)
+      - [Systemd](usage/configuration/systemd-with-workers/README.md)
   - [Administration](usage/administration/README.md)
     - [Admin API](usage/administration/admin_api/README.md)
       - [Account Validity](admin_api/account_validity.md)
diff --git a/docs/admin_api/server_notices.md b/docs/admin_api/server_notices.md
index 323138491a..ee306eab73 100644
--- a/docs/admin_api/server_notices.md
+++ b/docs/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.
diff --git a/docs/metrics-howto.md b/docs/metrics-howto.md
index 8f1f11f2b2..3d4098ab94 100644
--- a/docs/metrics-howto.md
+++ b/docs/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
diff --git a/docs/presence_router_module.md b/docs/presence_router_module.md
index face54fe2b..4cff8236ae 100644
--- a/docs/presence_router_module.md
+++ b/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.
 
diff --git a/docs/upgrade.md b/docs/upgrade.md
index b394d0c163..07b1c13445 100644
--- a/docs/upgrade.md
+++ b/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_update_user_dir]: workers.md#updating-the-user-directory
+[v1_59_notify_ases_from]: usage/configuration/workers.md#notifying-application-services
+[v1_59_update_user_dir]: usage/configuration/workers.md#updating-the-user-directory
 
 
 # Upgrading to v1.58.0
@@ -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
@@ -1286,7 +1286,7 @@ has been updated to include reverse proxy directives for
 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
diff --git a/docs/usage/administration/admin_api/background_updates.md b/docs/usage/administration/admin_api/background_updates.md
index 9f6ac7d567..3cd0201b69 100644
--- a/docs/usage/administration/admin_api/background_updates.md
+++ b/docs/usage/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](../../configuration/user_directory.md) if it is stale or out of sync.
diff --git a/docs/usage/administration/understanding_synapse_through_grafana_graphs.md b/docs/usage/administration/understanding_synapse_through_grafana_graphs.md
index c365cc3923..6d6db0ebfe 100644
--- a/docs/usage/administration/understanding_synapse_through_grafana_graphs.md
+++ b/docs/usage/administration/understanding_synapse_through_grafana_graphs.md
@@ -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](../configuration/workers.md) 
 to make use of multiple CPU cores / multiple machines for your homeserver.
 
diff --git a/docs/CAPTCHA_SETUP.md b/docs/usage/configuration/CAPTCHA_SETUP.md
index 49419ce8df..49419ce8df 100644
--- a/docs/CAPTCHA_SETUP.md
+++ b/docs/usage/configuration/CAPTCHA_SETUP.md
diff --git a/docs/application_services.md b/docs/usage/configuration/application_services.md
index e4592010a2..e4592010a2 100644
--- a/docs/application_services.md
+++ b/docs/usage/configuration/application_services.md
diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md
index 9fbc328042..9add017ca1 100644
--- a/docs/usage/configuration/config_documentation.md
+++ b/docs/usage/configuration/config_documentation.md
@@ -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`
 
@@ -470,9 +470,9 @@ Valid resource names are:
 
 * `metrics`: the metrics interface. See [here](../../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'.)
 
@@ -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
@@ -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`
@@ -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'.
@@ -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`.
diff --git a/docs/consent_tracking.md b/docs/usage/configuration/consent_tracking.md
index fb1fec80fe..fb1fec80fe 100644
--- a/docs/consent_tracking.md
+++ b/docs/usage/configuration/consent_tracking.md
diff --git a/docs/message_retention_policies.md b/docs/usage/configuration/message_retention_policies.md
index 7f3e5359f1..70d5a61a58 100644
--- a/docs/message_retention_policies.md
+++ b/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
diff --git a/docs/server_notices.md b/docs/usage/configuration/server_notices.md
index 339d10a0ab..04aa806732 100644
--- a/docs/server_notices.md
+++ b/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](../../admin_api/server_notices.md).
diff --git a/docs/structured_logging.md b/docs/usage/configuration/structured_logging.md
index d43dc9eb6e..d43dc9eb6e 100644
--- a/docs/structured_logging.md
+++ b/docs/usage/configuration/structured_logging.md
diff --git a/docs/synctl_workers.md b/docs/usage/configuration/synctl_workers.md
index 15e37f608d..15e37f608d 100644
--- a/docs/synctl_workers.md
+++ b/docs/usage/configuration/synctl_workers.md
diff --git a/docs/systemd-with-workers/README.md b/docs/usage/configuration/systemd-with-workers/README.md
index d516501085..d516501085 100644
--- a/docs/systemd-with-workers/README.md
+++ b/docs/usage/configuration/systemd-with-workers/README.md
diff --git a/docs/systemd-with-workers/system/matrix-synapse-worker@.service b/docs/usage/configuration/systemd-with-workers/system/matrix-synapse-worker@.service
index 8f5c44c9d4..8f5c44c9d4 100644
--- a/docs/systemd-with-workers/system/matrix-synapse-worker@.service
+++ b/docs/usage/configuration/systemd-with-workers/system/matrix-synapse-worker@.service
diff --git a/docs/systemd-with-workers/system/matrix-synapse.service b/docs/usage/configuration/systemd-with-workers/system/matrix-synapse.service
index 0c73fb55fb..0c73fb55fb 100644
--- a/docs/systemd-with-workers/system/matrix-synapse.service
+++ b/docs/usage/configuration/systemd-with-workers/system/matrix-synapse.service
diff --git a/docs/systemd-with-workers/system/matrix-synapse.target b/docs/usage/configuration/systemd-with-workers/system/matrix-synapse.target
index e0eba1b342..e0eba1b342 100644
--- a/docs/systemd-with-workers/system/matrix-synapse.target
+++ b/docs/usage/configuration/systemd-with-workers/system/matrix-synapse.target
diff --git a/docs/systemd-with-workers/workers/background_worker.yaml b/docs/usage/configuration/systemd-with-workers/workers/background_worker.yaml
index 9fbfbda7db..9fbfbda7db 100644
--- a/docs/systemd-with-workers/workers/background_worker.yaml
+++ b/docs/usage/configuration/systemd-with-workers/workers/background_worker.yaml
diff --git a/docs/systemd-with-workers/workers/event_persister.yaml b/docs/usage/configuration/systemd-with-workers/workers/event_persister.yaml
index 9bc6997bad..9bc6997bad 100644
--- a/docs/systemd-with-workers/workers/event_persister.yaml
+++ b/docs/usage/configuration/systemd-with-workers/workers/event_persister.yaml
diff --git a/docs/systemd-with-workers/workers/federation_sender.yaml b/docs/usage/configuration/systemd-with-workers/workers/federation_sender.yaml
index 5c591aec2c..5c591aec2c 100644
--- a/docs/systemd-with-workers/workers/federation_sender.yaml
+++ b/docs/usage/configuration/systemd-with-workers/workers/federation_sender.yaml
diff --git a/docs/systemd-with-workers/workers/generic_worker.yaml b/docs/usage/configuration/systemd-with-workers/workers/generic_worker.yaml
index 6e7b60886e..6e7b60886e 100644
--- a/docs/systemd-with-workers/workers/generic_worker.yaml
+++ b/docs/usage/configuration/systemd-with-workers/workers/generic_worker.yaml
diff --git a/docs/systemd-with-workers/workers/media_worker.yaml b/docs/usage/configuration/systemd-with-workers/workers/media_worker.yaml
index eb34d12492..eb34d12492 100644
--- a/docs/systemd-with-workers/workers/media_worker.yaml
+++ b/docs/usage/configuration/systemd-with-workers/workers/media_worker.yaml
diff --git a/docs/systemd-with-workers/workers/pusher_worker.yaml b/docs/usage/configuration/systemd-with-workers/workers/pusher_worker.yaml
index 46e22c6f06..46e22c6f06 100644
--- a/docs/systemd-with-workers/workers/pusher_worker.yaml
+++ b/docs/usage/configuration/systemd-with-workers/workers/pusher_worker.yaml
diff --git a/docs/templates.md b/docs/usage/configuration/templates.md
index 453ac90dd8..453ac90dd8 100644
--- a/docs/templates.md
+++ b/docs/usage/configuration/templates.md
diff --git a/docs/jwt.md b/docs/usage/configuration/user_authentication/jwt.md
index 2e262583a7..6f4cc444bc 100644
--- a/docs/jwt.md
+++ b/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
diff --git a/docs/password_auth_providers.md b/docs/usage/configuration/user_authentication/password_auth_providers.md
index dc0dfffa21..dc0dfffa21 100644
--- a/docs/password_auth_providers.md
+++ b/docs/usage/configuration/user_authentication/password_auth_providers.md
diff --git a/docs/openid.md b/docs/usage/configuration/user_authentication/single_sign_on/openid.md
index 87ebea4c29..d2726c2caa 100644
--- a/docs/openid.md
+++ b/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
diff --git a/docs/sso_mapping_providers.md b/docs/usage/configuration/user_authentication/single_sign_on/sso_mapping_providers.md
index 9f5e5fbbe1..9d8efed4be 100644
--- a/docs/sso_mapping_providers.md
+++ b/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
diff --git a/docs/user_directory.md b/docs/usage/configuration/user_directory.md
index c4794b04cf..31da9fd4b3 100644
--- a/docs/user_directory.md
+++ b/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.
 
diff --git a/docs/workers.md b/docs/usage/configuration/workers.md
index 3137ef0981..e6a7426874 100644
--- a/docs/workers.md
+++ b/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](setup/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
@@ -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`).
@@ -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
diff --git a/docs/welcome_and_overview.md b/docs/welcome_and_overview.md
index 451759f06e..8a92865020 100644
--- a/docs/welcome_and_overview.md
+++ b/docs/welcome_and_overview.md
@@ -21,9 +21,9 @@ This documentation covers topics for **installation**, **configuration** and
 
 * Learn how to [read log lines](usage/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
   Synapse instance's performance.