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 spec.matrix.org.

Developers looking to use Matrix should join #matrix-dev:matrix.org on Matrix for help.

Spec authors and proposal writers are welcome to join #matrix-spec:matrix.org. We welcome contributions! See CONTRIBUTING.rst for details.

Structure

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: https://gohugo.io/getting-started/installing
  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 #matrix-docs:matrix.org 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/dump-swagger.py 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 https://github.com/matrix-org/matrix-doc/issues.

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