File List
Not logged in

Files of check-in [d26d71cd86] in directory wiki_references/2019/software/mail_and_messaging/matrix_org/src_from_GitHub/the_repository_clones/matrix-doc   [history]

Matrix Specification

This repository contains the Matrix Specification, rendered at

Developers looking to use Matrix should join on Matrix for help.

Spec authors and proposal writers are welcome to join We welcome contributions! See CONTRIBUTING.rst for details.


The Matrix spec is compiled with Hugo (a static site generator) with the following structure:

It also has the following top-level file:

Additionally, the following directories may be of interest:

Authoring changes to the spec

Please read CONTRIBUTING.rst before authoring a change to the spec. Note that spec authoring takes place after an MSC has been accepted, not as part of a proposal itself.

  1. Install the extended version (often the OS default) of Hugo:
  2. Run git submodule update --init --recursive for good measure.
  3. Run npm i to install the dependencies. Note that this will require NodeJS to be installed.
  4. Run npm run get-proposals to seed proposal data. This is merely for populating the content of the "Spec Change Proposals" page and is not required.
  5. Run hugo serve to run a local webserver which builds whenever a file change is detected. If watching doesn't appear to be working for you, try hugo serve --disableFastRender instead.
  6. Edit the specification 🙂

We use a highly customized Docsy theme for our generated site, which uses Bootstrap and Font Awesome. If you're looking at making design-related changes to the spec site, please coordinate with us in before opening a PR.

Building the specification

If for some reason you're not a CI/CD system and want to render a static version of the spec for yourself, follow the above steps for authoring changes to the specification and instead of hugo serve run hugo -d "spec" - this will generate the spec to /spec. If you'd like to serve the spec off a path instead of a domain root (eg: /unstable), add --baseURL "/unstable" to the hugo -d "spec" command.

For building the swagger definitions, create a python3 virtualenv and activate it. Then run pip install -r ./scripts/requirements.txt and finally python ./scripts/ to generate it to ./scripts/swagger/api-docs.json. To make use of the generated file, there are a number of options:

Issue tracking

Specification issues are tracked on github at

See meta/github-labels.rst for information on what the labels mean.