Add a glossary to the Docs

CONTENT.md

@@ -356,3 +356,22 @@ To keep documentation on matrix.org tidy and approachable, it needs to be sorted
 Images make concepts easier to understand than walls of text. Screenshots make the documentation easier to follow in the onboarding and community sections. Diagrams and other illustrations can help break down more technical or complicated documentation.
 
 We are happy to review your documentation contributions and help you with any questions that you may end up with.
+
+### Glossary
+
+The glossary at [`/docs/glossary/`](https://matrix.org/docs/glossary/) defines the words, jargon, and acronyms used across Matrix and The Matrix.org Foundation. All entries live in a single file, [`/content/docs/glossary/terms.toml`](https://github.com/matrix-org/matrix.org/blob/main/content/docs/glossary/terms.toml), grouped loosely by category. You do not need to know Markdown, TOML tooling, or how the site builds to contribute — the file can be edited directly from GitHub's web UI.
+
+To add a term, append the following template to the end of `terms.toml`:
+
+```toml
+[[terms]]
+term = "My term"
+category = "Pick an existing category from the file, or introduce a new one"
+aliases = ["Optional alternate names or abbreviations"]
+definition = "One or two plain-language sentences explaining the term."
+learn_more = "/docs/some/relevant/page/#anchor" # optional, internal or external link
+```
+
+Only `term` and `definition` are required; `category`, `aliases`, and `learn_more` can be omitted. Terms don't need to be added in alphabetical order — the page sorts and groups them itself.
+
+If a term is really about the correct spelling or capitalisation of an official Matrix or Foundation name rather than what it means, it likely belongs on the [style guide](https://matrix.org/branding/#commonly-used-terms) instead.

content/docs/glossary/_index.md

@@ -0,0 +1,9 @@
++++
+title = "Glossary"
+weight = 500
+template = "docs/glossary.html"
+[extra]
+tile = "Definitions for the words and acronyms used across Matrix"
+meta_description = "Definitions for the terms, jargon, and acronyms used across Matrix and The Matrix.org Foundation."
+updated = "2026-07-15T00:00:00Z"
++++

content/docs/glossary/terms.toml

@@ -0,0 +1,158 @@
+# Glossary entries shown on /docs/glossary/.
+#
+# To add a term, append a new [[terms]] block below (alphabetical order isn't
+# required - the page sorts them itself). Only `term` and `definition` are
+# required.
+#
+#   [[terms]]
+#   term = "Your term"
+#   category = "One of the categories used below, or a new one"
+#   aliases = ["Optional alternate names or abbreviations"]
+#   definition = "One or two plain-language sentences."
+#   learn_more = "/docs/some/relevant/page/#anchor"   # optional, internal or external
+
+[[terms]]
+term = "Homeserver"
+category = "Core concepts"
+aliases = ["HS"]
+definition = "A server that hosts Matrix user accounts and participates in the network. Every account belongs to exactly one homeserver, identified by that server's domain."
+learn_more = "/docs/matrix-concepts/elements-of-matrix/#homeserver"
+
+[[terms]]
+term = "Client"
+category = "Core concepts"
+definition = "An application people use to read and send messages on Matrix, such as Element. Clients talk to a homeserver, never directly to other clients."
+learn_more = "/docs/matrix-concepts/elements-of-matrix/#client"
+
+[[terms]]
+term = "Federation"
+category = "Core concepts"
+definition = "The process by which independently-run homeservers exchange room data with each other, so users on different servers can share rooms without depending on a central server."
+learn_more = "/docs/matrix-concepts/elements-of-matrix/"
+
+[[terms]]
+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\"."
+learn_more = "/docs/matrix-concepts/elements-of-matrix/#homeserver"
+
+[[terms]]
+term = "Room"
+category = "Core concepts"
+definition = "A conversation, shared between the homeservers of everyone taking part. Each participating server keeps its own local copy of the room, which is kept in sync with the others."
+learn_more = "/docs/matrix-concepts/rooms_and_events/"
+
+[[terms]]
+term = "Room ID"
+category = "Core concepts"
+definition = "The internal, permanent identifier of a room, written as `!opaqueid:example.com`. Unlike a room's published address, it never changes for the lifetime of the room."
+learn_more = "/docs/matrix-concepts/rooms_and_events/"
+
+[[terms]]
+term = "Event"
+category = "Core concepts"
+definition = "A single timestamped, signed item in a room's history: a message, a membership change, a room setting being updated, and so on. Rooms are built up from a directed acyclic graph of events."
+learn_more = "/docs/matrix-concepts/rooms_and_events/"
+
+[[terms]]
+term = "State event"
+category = "Core concepts"
+definition = "An event that represents a piece of persistent room state (such as the room name, topic, or a member's membership) rather than a one-off message. Only the latest state event for a given type and key is considered current."
+learn_more = "/docs/matrix-concepts/rooms_and_events/"
+
+[[terms]]
+term = "Power level"
+category = "Core concepts"
+aliases = ["PL"]
+definition = "A per-user or per-action number in a room that determines what a user is allowed to do, such as sending certain event types, kicking, or banning."
+learn_more = "/docs/matrix-concepts/rooms_and_events/#administration-privileges"
+
+[[terms]]
+term = "Application Service"
+category = "Core concepts"
+aliases = ["AppService"]
+definition = "A privileged piece of software, registered with a homeserver, that can puppet many virtual users and rooms at once. Bridges and some advanced bots are built as Application Services."
+learn_more = "https://spec.matrix.org/latest/application-service-api/"
+
+[[terms]]
+term = "Bridge"
+category = "Core concepts"
+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."
+learn_more = "/ecosystem/bridges/"
+
+[[terms]]
+term = "Identity server"
+category = "Core concepts"
+definition = "A separate, optional service that maps third-party identifiers (such as email addresses or phone numbers) to Matrix IDs, used when inviting someone by contact detail instead of by their Matrix ID."
+
+[[terms]]
+term = "End-to-end encryption"
+category = "Security"
+aliases = ["E2EE"]
+definition = "Encryption where messages are only readable by the sending and receiving devices, not by the homeservers relaying them. Matrix implements this using the Olm and Megolm cryptographic ratchets."
+learn_more = "/docs/matrix-concepts/end-to-end-encryption/"
+
+[[terms]]
+term = "Device verification"
+category = "Security"
+definition = "The process of two devices confirming each other's cryptographic identity keys out-of-band, so they can trust that messages are really coming from who they claim to be from."
+learn_more = "/docs/matrix-concepts/end-to-end-encryption/#blocking-verifying-devices"
+
+[[terms]]
+term = "Cross-signing"
+category = "Security"
+definition = "A mechanism where a user signs their own devices with a private master key, so other users only need to verify that one master key to trust all of that user's current and future devices."
+
+[[terms]]
+term = "Key backup"
+category = "Security"
+definition = "An encrypted, server-side backup of a user's message decryption keys, so they aren't lost if all of a user's devices are lost or logged out at once."
+
+[[terms]]
+term = "Unable to decrypt"
+category = "Security"
+aliases = ["UTD"]
+definition = "An error state shown for a message a client received but could not decrypt, usually because it never obtained the room key for that message."
+
+[[terms]]
+term = "Account locking"
+category = "Trust & Safety"
+definition = "A reversible action where a user is prevented from logging in to their account, but the account itself is preserved in place."
+
+[[terms]]
+term = "Account suspension"
+category = "Trust & Safety"
+definition = "A reversible action similar to locking, except the user can still log in and read their account; they just cannot write (send messages, join rooms, and so on)."
+
+[[terms]]
+term = "Account deactivation"
+category = "Trust & Safety"
+definition = "A destructive, irreversible action where an account is removed from all rooms and permanently deleted."
+
+[[terms]]
+term = "Working Group"
+category = "Governance"
+aliases = ["WG"]
+definition = "A standing group, formed under the Foundation's Governing Board, focused on getting a specific area of work done - for example events, or a part of the ecosystem."
+learn_more = "/foundation/working-groups/"
+
+[[terms]]
+term = "Governing Board"
+category = "Governance"
+aliases = ["GB"]
+definition = "The organ of The Matrix.org Foundation through which the ecosystem participates in its governance, made up of representatives elected or appointed from across the community."
+learn_more = "/foundation/governing-board/"
+
+[[terms]]
+term = "Spec Core Team"
+category = "Governance"
+aliases = ["SCT"]
+definition = "The team responsible for stewarding the Matrix specification itself, including reviewing and merging Matrix Spec Changes (MSCs)."
+
+[[terms]]
+term = "Matrix Spec Change"
+category = "Governance"
+aliases = ["MSC"]
+definition = "A proposal to change or extend the Matrix specification, following the process defined by the Spec Core Team."
+learn_more = "https://spec.matrix.org/proposals/"

navigation.toml

@@ -28,9 +28,14 @@ title = "Categories"
 href = "/category/"
 
 [[header]]
+id = "docs"
 title = "Docs"
 href = "/docs/"
 
+[[header.children]]
+title = "Glossary"
+href = "/docs/glossary/"
+
 [[header]]
 title = "Ecosystem"
 section = "ecosystem"

sass/_base.scss

@@ -18,6 +18,14 @@
     --borders-color: #ddd;
 
     --notice-box-color: #ffcb006b;
+
+    // Tokens for the shared breadcrumb/page-header component below. Kept
+    // distinct from the older --borders-color/--color-text-light pair above
+    // rather than merged into them, since those are already used with their
+    // own (slightly different) shades elsewhere.
+    --color-border: #d2d2d2;
+    --color-text-muted: #555;
+    --color-bg-tint: #fafafa;
 }
 
 * {

sass/_breadcrumb.scss

@@ -0,0 +1,81 @@
+// Breadcrumb navigation
+// Used via macros/breadcrumb.html. Two contexts:
+//   1. Inside .page-header (dark background) - text is white/muted-white
+//   2. Inside .detail-page (light background) - text is muted grey
+
+.breadcrumb {
+    ol {
+        display: flex;
+        flex-wrap: wrap;
+        align-items: center;
+        list-style: none;
+        margin: 0;
+        padding: 0;
+        gap: 0.25rem;
+        font-size: 0.85rem;
+    }
+
+    li {
+        display: flex;
+        align-items: center;
+
+        // Chevron separator before every item except the first
+        & + li::before {
+            content: "/";
+            margin-right: 0.25rem;
+            opacity: 0.45;
+        }
+    }
+
+    a,
+    span {
+        text-decoration: none;
+        line-height: 1;
+    }
+
+    // Dark context (inside .page-header)
+    .page-header & {
+        margin-bottom: 0.75rem;
+
+        a {
+            color: rgb(255 255 255 / 70%);
+
+            &:hover {
+                color: #fff;
+            }
+        }
+
+        // 45% white only clears ~4.4:1 against the black hero background,
+        // just under AA's 4.5:1 for text; 60% keeps it safely above.
+        span {
+            color: rgb(255 255 255 / 60%);
+        }
+
+        li + li::before {
+            color: rgb(255 255 255 / 45%);
+        }
+    }
+
+    // Light context (inside .detail-page)
+    .detail-page & {
+        margin-bottom: 1.25rem;
+
+        a {
+            color: var(--color-text-muted);
+
+            &:hover {
+                color: var(--color-text);
+            }
+        }
+
+        // The current-page label is text, not decoration, so it still needs
+        // to clear WCAG AA (4.5:1); #aaa on white only manages ~2.3:1.
+        span {
+            color: var(--color-text-light);
+        }
+
+        li + li::before {
+            color: #ccc;
+        }
+    }
+}