Docs: Use something other than the document name to describe a page (#10399)

Our documentation has a history of using a document's name as a way to link to it, such as "See [workers.md]() for details". This makes sense when you're traversing a directory of files, but less sense when the files are abstracted away - as they are on the documentation website.

This PR changes the links to various documentation pages to something that fits better into the surrounding sentence, as you would when making any hyperlink on the web.
This commit is contained in:
Andrew Morgan 2021-07-15 12:47:55 +01:00 committed by GitHub
parent ac5c221208
commit c141455049
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
12 changed files with 22 additions and 23 deletions

1
changelog.d/10399.doc Normal file
View file

@ -0,0 +1 @@
Rewrite the text of links to be clearer in the documentation.

View file

@ -132,7 +132,7 @@ your domain, you can simply route all traffic through the reverse proxy by
updating the SRV record appropriately (or removing it, if the proxy listens on
8448).
See [reverse_proxy.md](reverse_proxy.md) for information on setting up a
See [the reverse proxy documentation](reverse_proxy.md) for information on setting up a
reverse proxy.
#### Option 3: add a .well-known file to delegate your matrix traffic
@ -303,7 +303,7 @@ We no longer actively recommend against using a reverse proxy. Many admins will
find it easier to direct federation traffic to a reverse proxy and manage their
own TLS certificates, and this is a supported configuration.
See [reverse_proxy.md](reverse_proxy.md) for information on setting up a
See [the reverse proxy documentation](reverse_proxy.md) for information on setting up a
reverse proxy.
### Do I still need to give my TLS certificates to Synapse if I am using a reverse proxy?

View file

@ -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 [server_notices.md](../server_notices.md) for more information.
can be used. See [the server notices documentation](../server_notices.md) for more information.

View file

@ -152,7 +152,7 @@ version of the policy. To do so:
* ensure that the consent resource is configured, as in the previous section
* ensure that server notices are configured, as in [server_notices.md](server_notices.md).
* ensure that server notices are configured, as in [the server notice documentation](server_notices.md).
* Add `server_notice_content` under `user_consent` in `homeserver.yaml`. For
example:

View file

@ -74,7 +74,7 @@ We no longer actively recommend against using a reverse proxy. Many admins will
find it easier to direct federation traffic to a reverse proxy and manage their
own TLS certificates, and this is a supported configuration.
See [reverse_proxy.md](reverse_proxy.md) for information on setting up a
See [the reverse proxy documentation](reverse_proxy.md) for information on setting up a
reverse proxy.
### Do I still need to give my TLS certificates to Synapse if I am using a reverse proxy?

View file

@ -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 [reverse_proxy.md](reverse_proxy.md) for instructions
reverse proxy: see [the reverse proxy documentation](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 [delegate.md](delegate.md) for instructions on how to set this up.
be sent. See [the delegation documentation](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,8 +44,8 @@ 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 [reverse_proxy.md](reverse_proxy.md) for instructions on how to correctly
configure a reverse proxy.
proxy: see [the reverse proxy documentation](reverse_proxy.md) for instructions on how
to correctly configure a reverse proxy.
### Known issues

View file

@ -28,7 +28,7 @@ minimal.
### The Replication Protocol
See [tcp_replication.md](tcp_replication.md)
See [the TCP replication documentation](tcp_replication.md).
### The Slaved DataStore

View file

@ -21,7 +21,7 @@ port 8448. Where these are different, we refer to the 'client port' and the
'federation port'. See [the Matrix
specification](https://matrix.org/docs/spec/server_server/latest#resolving-server-names)
for more details of the algorithm used for federation connections, and
[delegate.md](delegate.md) for instructions on setting up delegation.
[Delegation](delegate.md) for instructions on setting up delegation.
**NOTE**: Your reverse proxy must not `canonicalise` or `normalise`
the requested URI in any way (for example, by decoding `%xx` escapes).

View file

@ -4,7 +4,7 @@
channel whereby server administrators can send messages to users on the server.
They are used as part of communication of the server polices (see
[consent_tracking.md](consent_tracking.md)), however the intention is that
[Consent Tracking](consent_tracking.md)), however the intention is that
they may also find a use for features such as "Message of the day".
This is a feature specific to Synapse, but it uses standard Matrix

View file

@ -412,7 +412,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
[docs/postgres.md](../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
@ -427,7 +427,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
[docs/reverse_proxy.md](../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:
@ -454,7 +454,7 @@ so, you will need to edit `homeserver.yaml`, as follows:
`cert.pem`).
For a more detailed guide to configuring your server for federation, see
[federate.md](../federate.md).
[Federation](../federate.md).
### Client Well-Known URI
@ -566,9 +566,7 @@ on your server even if `enable_registration` is `false`.
### Setting up a TURN server
For reliable VoIP calls to be routed via this homeserver, you MUST configure
a TURN server. See
[docs/turn-howto.md](../turn-howto.md)
for details.
a TURN server. See [TURN setup](../turn-howto.md) for details.
### URL previews

View file

@ -14,7 +14,7 @@ contains an example configuration for the `federation_reader` worker.
## Synapse configuration files
See [workers.md](../workers.md) for information on how to set up the
See [the worker documentation](../workers.md) for information on how to set up the
configuration files and reverse-proxy correctly.
Below is a sample `federation_reader` worker configuration file.
```yaml

View file

@ -73,7 +73,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
[reverse_proxy.md](reverse_proxy.md) for information on setting up a reverse
[the reverse proxy documentation](reverse_proxy.md) for information on setting up a reverse
proxy.
When using workers, each worker process has its own configuration file which
@ -170,8 +170,8 @@ 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
[synctl_workers.md](synctl_workers.md).
[Systemd with Workers](systemd-with-workers). To use `synctl`, see
[Using synctl with Workers](synctl_workers.md).
## Available worker applications