diff --git a/docs/usage/administration/README.md b/docs/administration/README.md
index e1e57546ab..e1e57546ab 100644
--- a/docs/usage/administration/README.md
+++ b/docs/administration/README.md
diff --git a/docs/usage/administration/admin_faq.md b/docs/administration/admin_faq.md
index e349a4e34f..4f06f0ac11 100644
--- a/docs/usage/administration/admin_faq.md
+++ b/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`.
@@ -122,7 +122,7 @@ 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](../../setup/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
diff --git a/docs/usage/administration/database_maintenance_tools.md b/docs/administration/database_maintenance_tools.md
index 92b805d413..c6cf0c990e 100644
--- a/docs/usage/administration/database_maintenance_tools.md
+++ b/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)
diff --git a/docs/manhole.md b/docs/administration/manhole.md
index 4e5bf833ce..1d04fc244c 100644
--- a/docs/manhole.md
+++ b/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
diff --git a/docs/metrics-howto.md b/docs/administration/metrics-howto.md
index 3d4098ab94..c9156f2783 100644
--- a/docs/metrics-howto.md
+++ b/docs/administration/metrics-howto.md
@@ -92,7 +92,7 @@
## Monitoring workers
-To monitor a Synapse installation using [workers](usage/configuration/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/usage/administration/monthly_active_users.md b/docs/administration/monthly_active_users.md
index d4e9037284..c0e233d234 100644
--- a/docs/usage/administration/monthly_active_users.md
+++ b/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
diff --git a/docs/usage/administration/monitoring/reporting_homeserver_usage_statistics.md b/docs/administration/reporting_homeserver_usage_statistics.md
index 4e53f9883a..7f3b124529 100644
--- a/docs/usage/administration/monitoring/reporting_homeserver_usage_statistics.md
+++ b/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. |
-| `event_cache_size` | int | The configured [`event_cache_size`](../../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`](../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
diff --git a/docs/usage/administration/request_log.md b/docs/administration/request_log.md
index 82f5ac7b96..82f5ac7b96 100644
--- a/docs/usage/administration/request_log.md
+++ b/docs/administration/request_log.md
diff --git a/docs/usage/administration/state_groups.md b/docs/administration/state_groups.md
index f1dee7accf..f1dee7accf 100644
--- a/docs/usage/administration/state_groups.md
+++ b/docs/administration/state_groups.md
diff --git a/docs/usage/administration/understanding_synapse_through_grafana_graphs.md b/docs/administration/understanding_synapse_through_grafana_graphs.md
index 6d6db0ebfe..56d47adf6e 100644
--- a/docs/usage/administration/understanding_synapse_through_grafana_graphs.md
+++ b/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](../configuration/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.
diff --git a/docs/usage/administration/useful_sql_for_admins.md b/docs/administration/useful_sql_for_admins.md
index f3b97f9576..f3b97f9576 100644
--- a/docs/usage/administration/useful_sql_for_admins.md
+++ b/docs/administration/useful_sql_for_admins.md
|
