Add a glossary to the Docs by MTRNord · Pull Request #3536 · matrix-org/matrix.org

MTRNord · 2026-07-15T10:27:03Z

Description

This fixes #2262 while hopefully not ending up in another unmaintained FAQ :)

Related issues

(also mildly related to #3534 and #3518 since this is cherry picked from the same local branch I have for all this work)

Role

Website & Content WG

Timeline

Whenever

Signoff

Please sign off your individual commits.

Signed-off-by: MTRNord <MTRNord@users.noreply.github.com>

cloudflare-workers-and-pages · 2026-07-15T10:40:39Z

Deploying matrix-website with Cloudflare Pages

Latest commit:	`ec2b00e`
Status:	✅ Deploy successful!
Preview URL:	https://77e407bc.matrix-website.pages.dev
Branch Preview URL:	https://mtrnord-glossary.matrix-website.pages.dev

View logs

HarHarLinks · 2026-07-15T10:32:26Z

 title = "Docs"
 href = "/docs/"

+[[header.children]]


spicy, at this point we should probably add all the docs sections (except legacy?)

HarHarLinks · 2026-07-15T10:39:48Z

+term = "Matrix ID"
+category = "Core concepts"
+aliases = ["MXID", "User ID"]
+definition = "A user's identifier, made up of a local part and the domain of their homeserver, written as `@username:example.com`. Pronounced \"at username on example dot com\"."


can get removed from branding then

HarHarLinks · 2026-07-15T10:42:46Z

/branding should probably inherit this layout. can be a followup pr

Switches terms.toml from a flat [[terms]] array with a category string field to one [[terms.<category>]] array per category (terms.core, terms.security, terms.trust_safety, terms.governance), and updates the template to read the new shape. Also fixes the category display order along the way: group_by(attribute= "category") in the old template produced whatever order Tera's grouping happened to yield, not a meaningful one (Trust & Safety was first). Tera has no map literals to build a sorted {label, terms} list dynamically, so the template now uses two parallel arrays (category_labels/category_keys) kept in alphabetical order by hand instead. Signed-off-by: MTRNord <MTRNord@users.noreply.github.com>

Each term now gets a stable id="term-<slug>" and a "#" permalink next to its name (revealed on hover/focus, same idea as the client-card anchor links elsewhere), so a specific definition can be linked to directly instead of only the page as a whole. Signed-off-by: MTRNord <MTRNord@users.noreply.github.com>

A plain h2 on white didn't read as a section boundary at a glance across two dozen+ terms in 4 categories. Gives the sticky category heading a subtle background tint (the same --color-bg-tint used by the docs sidebar elsewhere) and bold weight, without changing its structure - kept deliberately small since an earlier, more decorative attempt (bordered card wrapper, coloured accent bar) ended up reading like a different site's design language entirely. Signed-off-by: MTRNord <MTRNord@users.noreply.github.com>

- Rename "Matrix ID" to "Matrix user ID" per review, keeping "Matrix ID" as an alias alongside MXID/User ID - matches how the term is actually used in running text more often than as a standalone noun. - Give "Spec Core Team" a learn_more link to its section on /foundation/about/. Signed-off-by: MTRNord <MTRNord@users.noreply.github.com>

vodozemac is the Rust library implementing Matrix's E2EE ratchets (Olm and Megolm), replacing the deprecated libolm - a better fit for the glossary than the branding page's spelling/pronunciation table. Carries over both links from the original branding.md row (the Croatian dictionary entry for "vodozémac" and the YouTube pronunciation clip). Definitions are now rendered as inline markdown (`| markdown(inline=true) | safe`) instead of plain escaped text, so those links (and the existing `code`-style backticks used by a few other terms) actually render. Signed-off-by: MTRNord <MTRNord@users.noreply.github.com>

Signed-off-by: MTRNord <MTRNord@users.noreply.github.com>

HarHarLinks · 2026-07-15T11:22:06Z

+    }
+
+    // Only reveal the "#" permalink on hover/focus - it's a bonus for
+    // sighted mouse/keyboard users linking to a term, not something that


rip mobile users

maybe just reveal this always while in mobile view. make sure the touch area is big enough.

HarHarLinks · 2026-07-15T11:23:17Z

+                        {% if term.aliases %}
+                        <span class="glossary-aliases">({{ term.aliases | join(sep=", ") }})</span>
+                        {% endif %}
+                        <a href="#{{ term_id }}" class="glossary-term-anchor" aria-label="Link to {{ term.term }}">#</a>


this is a problem everywhere, but jumping to this anchor needs an offset considering the navbar etc:

uhhhh it does have one 🤔

Screensizes strike again...

i could imagine trying to scroll it to the middle would be a valid workaround? if that is even possible.

it could also be an idea to put a highlighting frame something around the currently selected term.

HarHarLinks · 2026-07-15T22:50:08Z

 | `#room:server.tld` | | Pronounced "[hash room on server dot tld](https://matrix.org/blog/wp-content/uploads/2014/09/Introducing-matrix.pdf)". |
 | `@user:server.tld` | | Pronounced "[at user on server dot tld](https://matrix.org/blog/wp-content/uploads/2014/09/Introducing-matrix.pdf)". |


MXID is already transferred, room alias can be too?

HarHarLinks · 2026-07-15T22:55:30Z

+        top: var(--navbar-height);
+        margin: 0;
+        padding: 0.5rem 0;
+        background-color: var(--color-bg-tint);


hm no i'm not convinced. that's not what i was looking for :/

HarHarLinks · 2026-07-15T22:59:07Z

+
+[[terms.core]]
+term = "Bridge"
+definition = "A form of Application Service that relays messages between Matrix and a third-party chat platform (for example IRC, Slack, or Discord), so users on either side can talk to each other."


oooh i think we have definitions of more details like puppeting and portalling and stuff somewhere. probably terms that are worth appearing here even if the details are only behind a link

i think bridges being appservices is strictly speaking also incorrect. a bridge is a component that unpacks one message completely, incl possible decryption, and then sends it to another network. a protocol converter is a component that only converts the protocol around a message without need to decrypt. something slide 25 https://docs.google.com/presentation/d/1hxRlyJ6SD3zXb2MPGmfigB0s9Yj4dsWBMtctNPv06IA/edit?usp=sharing (yay obscure documents)

HarHarLinks · 2026-07-15T23:05:25Z

+        padding: 0.5rem 0;
+        background-color: var(--color-bg-tint);
+        border-bottom: 1px solid var(--color-border);
+        font-size: 1.1rem;


Signed-off-by: MTRNord <MTRNord@users.noreply.github.com>

add a shared breadcrumb component and additional design tokens

2eada0a

Signed-off-by: MTRNord <MTRNord@users.noreply.github.com>

MTRNord requested a review from a team as a code owner July 15, 2026 10:27

add a glossary to the docs

7a67cab

Signed-off-by: MTRNord <MTRNord@users.noreply.github.com>

MTRNord force-pushed the MTRNord/glossary branch from 0791ab0 to 7a67cab Compare July 15, 2026 10:40

HarHarLinks reviewed Jul 15, 2026

View reviewed changes

Comment thread content/docs/glossary/terms.toml

HarHarLinks reviewed Jul 15, 2026

View reviewed changes

Comment thread templates/docs/glossary.html

HarHarLinks Jul 15, 2026

Copy link
Copy Markdown

Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

/branding should probably inherit this layout. can be a followup pr

HarHarLinks added missing content Something that would be expected to exist is missing. enhancement This would be an improvement to the website. labels Jul 15, 2026

MTRNord added 6 commits July 15, 2026 13:01

give the glossary the same docs sidebar as other docs pages

ccb30ad

Signed-off-by: MTRNord <MTRNord@users.noreply.github.com>

HarHarLinks reviewed Jul 15, 2026

View reviewed changes

MTRNord added 3 commits July 16, 2026 17:11

improve title size and scroll-margin-top

a5cf8ca

Signed-off-by: MTRNord <MTRNord@users.noreply.github.com>

fix scroll-margin-top for the terms

72047cd

Signed-off-by: MTRNord <MTRNord@users.noreply.github.com>

fix comment

ec2b00e

Signed-off-by: MTRNord <MTRNord@users.noreply.github.com>

		\| `#room:server.tld` \| \| Pronounced "[hash room on server dot tld](https://matrix.org/blog/wp-content/uploads/2014/09/Introducing-matrix.pdf)". \|
		\| `@user:server.tld` \| \| Pronounced "[at user on server dot tld](https://matrix.org/blog/wp-content/uploads/2014/09/Introducing-matrix.pdf)". \|

Uh oh!

Uh oh!

Conversation

MTRNord commented Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Related issues

Role

Timeline

Signoff

Uh oh!

cloudflare-workers-and-pages Bot commented Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying matrix-website with Cloudflare Pages

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

HarHarLinks Jul 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

MTRNord commented Jul 15, 2026 •

edited

Loading

cloudflare-workers-and-pages Bot commented Jul 15, 2026 •

edited

Loading

HarHarLinks Jul 16, 2026 •

edited

Loading