75 lines
3.0 KiB
Markdown
75 lines
3.0 KiB
Markdown
# Synapse Documentation
|
|
|
|
**The documentation is currently hosted [here](https://matrix-org.github.io/synapse).**
|
|
Please update any links to point to the new website instead.
|
|
|
|
## About
|
|
|
|
This directory currently holds a series of markdown files documenting how to install, use
|
|
and develop Synapse. The documentation is readable directly from this repository, but it is
|
|
recommended to instead browse through the [website](https://matrix-org.github.io/synapse) for
|
|
easier discoverability.
|
|
|
|
## Adding to the documentation
|
|
|
|
Most of the documentation currently exists as top-level files, as when organising them into
|
|
a structured website, these files were kept in place so that existing links would not break.
|
|
The rest of the documentation is stored in folders, such as `setup`, `usage`, and `development`
|
|
etc. **All new documentation files should be placed in structured folders.** For example:
|
|
|
|
To create a new user-facing documentation page about a new Single Sign-On protocol named
|
|
"MyCoolProtocol", one should create a new file with a relevant name, such as "my_cool_protocol.md".
|
|
This file might fit into the documentation structure at:
|
|
|
|
- Usage
|
|
- Configuration
|
|
- User Authentication
|
|
- Single Sign-On
|
|
- **My Cool Protocol**
|
|
|
|
Given that, one would place the new file under
|
|
`usage/configuration/user_authentication/single_sign_on/my_cool_protocol.md`.
|
|
|
|
Note that the structure of the documentation (and thus the left sidebar on the website) is determined
|
|
by the list in [SUMMARY.md](SUMMARY.md). The final thing to do when adding a new page is to add a new
|
|
line linking to the new documentation file:
|
|
|
|
```markdown
|
|
- [My Cool Protocol](usage/configuration/user_authentication/single_sign_on/my_cool_protocol.md)
|
|
```
|
|
|
|
## Building the documentation
|
|
|
|
The documentation is built with [mdbook](https://rust-lang.github.io/mdBook/), and the outline of the
|
|
documentation is determined by the structure of [SUMMARY.md](SUMMARY.md).
|
|
|
|
First, [get mdbook](https://github.com/rust-lang/mdBook#installation). Then, **from the root of the repository**,
|
|
build the documentation with:
|
|
|
|
```sh
|
|
mdbook build
|
|
```
|
|
|
|
The rendered contents will be outputted to a new `book/` directory at the root of the repository. Please note that
|
|
index.html is not built by default, it is created by copying over the file `welcome_and_overview.html` to `index.html`
|
|
during deployment. Thus, when running `mdbook serve` locally the book will initially show a 404 in place of the index
|
|
due to the above. Do not be alarmed!
|
|
|
|
You can also have mdbook host the docs on a local webserver with hot-reload functionality via:
|
|
|
|
```sh
|
|
mdbook serve
|
|
```
|
|
|
|
The URL at which the docs can be viewed at will be logged.
|
|
|
|
## Configuration and theming
|
|
|
|
The look and behaviour of the website is configured by the [book.toml](../book.toml) file
|
|
at the root of the repository. See
|
|
[mdbook's documentation on configuration](https://rust-lang.github.io/mdBook/format/config.html)
|
|
for available options.
|
|
|
|
The site can be themed and additionally extended with extra UI and features. See
|
|
[website_files/README.md](website_files/README.md) for details.
|