The matrix.org website is a Zola site whose git history needs a partial clone

A website repository, not the protocol itself

The repository is the public website for Matrix, and it is worth being clear about what that means. Matrix is a protocol, and the code that implements homeservers, clients and bridges lives in other repositories. What is here is the site that documents and presents it.

The build system tells you that immediately. The site is generated by Zola, a static site generator, and the repository is a collection of content, templates, styles and static assets rather than an application with a runtime. The top level shows the whole shape of it: a content directory, a partials directory, a sass directory, a static directory and a templates directory, with config.toml, navigation.toml and taxonomy.toml as the site configuration, and a build.sh script at the root.

There are also a few files that show how carefully the project is maintained. .rumdl.toml configures a markdown linter and .typos.toml configures a spell checker, so the prose in the content directory is checked for style the same way code would be. A .well-known directory holds the kind of files the web expects under that path, such as security and matrix server discovery responses.

So the audience is contributors to the Matrix project's public presence, plus anyone who wants to see how a mid-sized static site is organised and reviewed.

Why the README tells you to clone with blob filtering

The cloning section is the most unusual part of the README, and the numbers make the case for itself.

Due to historic growth and media, the repository is quite large. At the time of writing the full data is 1.18GiB, and the project suggests using --filter=blob:none on a fresh clone, which reduces the downloaded data to 612MiB by fetching only the things you actually need instead of all of the blob content.

The command is:

git clone --filter=blob:none [email protected]:matrix-org/matrix.org.git

A partial clone is different from a shallow clone, and the README is careful to point at two articles that explain why --depth=1 is not ideal and what the implications are. The distinction matters if you plan to contribute: a shallow clone gives you a short history with no ancestry, which makes blame output and rebasing against the real history awkward, while a partial clone keeps the full commit graph and fetches file contents on demand.

There is a second lesson in that section, which is that the size comes from media, not from code. The repository has accumulated enough images and downloads over its history that the object store is now larger than the site itself. That is a normal property of a long-lived public website, and it is also the kind of thing a project can only fix by rewriting history, which nobody wants to do.

Zola 0.20.0 and a local preview server

Building the site is deliberately uncomplicated. Install version 0.20.0 of Zola, clone the repository, and from the root of the repository type:

zola serve

Zola will build the website and start a web server, usually at http://127.0.0.1:1111.

That is the whole local workflow. There is no package manager step, no dependency install, and no build of application code, because a static site generator turns the files in the repository into HTML with nothing to compile at run time. The cost of that simplicity is that the generator version matters, and the README pins it: 0.20.0 is the version used to build the website in CI, as shown in the workflow file at .github/workflows/zola.yml.

The pin is the sort of detail that saves an afternoon. Zola's template language and configuration format change between versions, so a local preview running a different release than CI can produce a page that renders locally and fails the build, or the reverse. Installing the version the CI uses is what makes the local loop trustworthy.

And because the output is static, a preview is a complete preview. The page you see on http://127.0.0.1:1111 is built from the same content and templates that will be deployed, rather than an approximation assembled by a development server.

How a page is written and where it lands

The README points at two documents for the two kinds of question a contributor has. CONTRIBUTING.md self-documents the project's processes, and CONTENT.md covers how to write content for the website.

The directory layout answers the rest. Content is in the content directory, and the templates and partials directories hold the markup those content files are rendered with, so a change to how every page looks is a template change rather than an edit across every page. The sass directory holds the styles, and static holds files that are copied through unchanged, which is where images and downloads live. That split is also why the repository is large, since static assets accumulate.

The three toml files at the root are the site configuration. config.toml holds the general settings, navigation.toml the site navigation, and taxonomy.toml the taxonomy terms, which is how Zola models tags and categories. A build.sh script sits beside them for whatever the project does around a plain zola build.

The style tooling is worth noting because it explains the tone of the content. With a markdown linter configured in .rumdl.toml and a spell checker configured in .typos.toml, a pull request that introduces a typo or a formatting slip is caught by automation before a human reads it, and the working group spends its review time on whether the page is right rather than on whether the prose is tidy.

Asking first is part of the process

The opening paragraph of the README is about how to contribute, and it sets the expectation plainly.

If you want to contribute to the website, make sure the problem you are trying to fix or the feature you want to implement has been discussed in the issue tracker, and that the maintainers are interested in reviewing and merging such a contribution.

That is a two-part condition, and both parts matter. Discussion in the tracker is what stops someone spending an evening on a change that was never going to be wanted, and the second part is a check on your own expectations, since an interested maintainer is what makes the merge happen.

For questions about maintenance of the site specifically, the README points at the Website and Content Working Group, listed among the working groups on the Matrix Foundation site, and at a Matrix room, #matrix.org-website:matrix.org, reachable through the matrix.to link. So the project is a foundation working group with a chat room attached, which is a reasonable structure for a site that has to satisfy a legal and policy bar as well as a technical one.

The repository also carries a hacktoberfest topic tag, which means the project takes part in that event, and the first README paragraph is effectively the onboarding note for people arriving through it.

Three licence files and a licences directory

The licence situation is the one place where the repository listing is more informative than the README, and it needs care.

At the root there are four licence-related entries: LICENSE.md, LICENSE-Apache-2.0, LICENSE-CC-BY-SA, a LICENSES directory, and the Apache and Creative Commons attribution share alike texts side by side. The repository licence is recorded as a custom one that GitHub cannot classify, which in practice means the automated tooling will not tell you the terms.

The presence of an Apache 2.0 text and a CC BY-SA text in the same repository strongly suggests the conventional split for a project with both code and prose, where the software is under the permissive Apache licence and the written content is under the share-alike creative commons licence. That is a common pattern for exactly this kind of site, and it is also a pattern you want, because it means a translator or a documentation volunteer can reuse the content under clear terms. But the README does not state which file governs which part, so the mapping has to be confirmed in LICENSE.md rather than assumed.

For anyone who wants to reuse a paragraph from the Matrix documentation, that is the file to read first, and for anyone who wants to reuse the templates, the Apache text is the likely answer.

How the site is maintained

The repository is not archived, and the last push was on 2026-10-19, so the site is being worked on. There are no GitHub releases, which is what you would expect from a repository whose deployable output is a website rather than a package.

The continuous integration is visible in the repository too, through the .github/ directory and the Zola workflow the README points at, and the choice to pin one generator version in CI means the build is reproducible. A site that is built on every merge and served from the result does not need release tags, and its upgrade cycle is the generator's upgrade cycle.

The other thing worth noting is the scale the maintainers are working with. A 1.18GiB repository, a working group structure, a content guide, style automation and a review process are the costs of a public site for a protocol with a foundation behind it. The partial clone advice in the README is the tip of that: the history is heavy because the site is old and heavily illustrated, and the project has decided the better answer is to teach contributors how to fetch less, rather than to rewrite the past.

For a new contributor, the practical sequence is short. Clone with the filter, install Zola 0.20.0, run zola serve, read CONTRIBUTING.md and CONTENT.md, and take the question or the fix to the issue tracker before writing the page.

Editorial conclusion

matrix.org suits a contributor who wants to fix a page on the Matrix project website and is comfortable with a pull request, a Markdown content file and a static site build, and the partial clone advice makes a fresh checkout practical even on a modest connection. It is the wrong repository if you are looking for Matrix server or client code, and it is the wrong repository if you need to change the site design system without a maintainer conversation, since the project asks that features be discussed first. Verify first that Zola 0.20.0 is the version you install, because the CI build depends on it, and read CONTRIBUTING.md and CONTENT.md before you write a page, since they document the review and content processes the README points you to.

Frequently asked questions

Official sources

1. Issues
2. matrix-org/matrix.org on GitHub
3. Project website
4. README