Bump mdbook from 0.4.17 -> 0.5.2 and remove custom table-of-contents plugin by anoadragon453 · Pull Request #19356 · element-hq/synapse

anoadragon453 · 2026-01-07T16:25:33Z

Closes #19261.

Updates mdbook (the tool we use to build the Synapse documentation to 0.5.2. Notably, this brings the following features:

Built-in table-of-contents functionality. We can now remove our custom table-of-contents implementation (which looked a bit nicer, but didn't work unless you had the right zoom level in your browser).
Admonitions, which give us nice warning, note, important, etc. boxes.

Pull Request Checklist

Pull request is based on the develop branch
Pull request includes a changelog file. The entry should:
- Be a short description of your change which makes sense to users. "Fixed a bug that prevented receiving messages from other servers." instead of "Moved X method from EventStore to EventWorkerStore.".
- Use markdown where necessary, mostly for code blocks.
- End with either a period (.) or an exclamation mark (!).
- Start with a capital letter.
- Feel free to credit yourself, by adding a sentence "Contributed by @github_username." or "Contributed by [Your Name]." to the end of the entry.
Code style is correct (run the linters)

See https://github.com/rust-lang/mdBook/blob/master/CHANGELOG.md#05-migration-guide

We can now rely on the default functionality built into mdbook for this.

The custom theme is still needed for the version picker. Technically we could add this HTML in the version-picker.js, but there's no guarantee that the HTML IDs etc. wouldn't change out from under us. We also no longer need the next/prev hiding plugin, as the original point of it was to prevent those UI elements from interfering with our custom TOC.

No longer needed as the original purpose was to stop them from interfering with the TOC on desktop.

"sections" was renamed to "items" in rust-lang/mdBook#2813

As they're generally prettier. Requires #19356

devonh

Changes look good to me.
Looking forward to the new admonition boxes!

...assuming the tests pass of course 🙃

htmltest began to raise warnings about links to directories which do actually work in practice. I believe this is an artifact of the print renderer. Let's just skip checking its results. The same content is still present in the rest of the generated HTML.

MadLittleMods · 2026-01-07T18:07:03Z

.github/workflows/docs-pr.yaml

        uses: peaceiris/actions-mdbook@ee69d230fe19748b7abf22df32acaa93833fad08 # v2.0.0
        with:
-          mdbook-version: '0.4.17'
+          mdbook-version: '0.5.2'


I assume this change is spawning from #19341 (comment)

Actually, I ran into my own issue here: https://github.com/element-hq/synapse/actions/runs/20788621286/job/59704957332?pr=19356#step:5:26

htmltest started at 04:33:09 on book ======================================================================== print.html target is a directory, href lacks trailing slash --- print.html --> systemd-with-workers target is a directory, href lacks trailing slash --- print.html --> systemd-with-workers target is a directory, href lacks trailing slash --- print.html --> systemd-with-workers target is a directory, href lacks trailing slash --- print.html --> usage/administration/admin_api target is a directory, href lacks trailing slash --- print.html --> usage/administration/admin_api ... etc

Though I was hoping to kill two birds with one stone. Sadly it looks like this just makes print.html no longer a valid link: https://github.com/element-hq/synapse/actions/runs/20790804070/job/59712251565?pr=19356#step:5:29

htmltest started at 05:43:09 on book ======================================================================== postgres.html target does not exist --- postgres.html --> print.html code_style.html target does not exist --- code_style.html --> print.html structured_logging.html target does not exist --- structured_logging.html --> print.html admin_api/statistics.html target does not exist --- admin_api/statistics.html --> ../print.html admin_api/register_api.html target does not exist --- admin_api/register_api.html --> ../print.html ... etc

We could just replace print.html with an empty file, but I really wish there was just a config option on htmltest to ignore a regex of file paths...

Have done the workaround and left a sad comment.

MadLittleMods · 2026-01-07T18:09:20Z

docs/.htmltest.yml

+# Don't check external links, as that requires network access and is slow.
+CheckExternal: false


For reference, we previously had this config as we used --skip-external CLI arg before which is translated to options["CheckExternal"] = false.

synapse/.github/workflows/docs-pr.yaml

Line 71 in cbc5469

./htmltest book --skip-external

MadLittleMods · 2026-01-07T18:09:57Z

.github/workflows/docs-pr.yaml

        # Then run htmltest (without checking external links since that involves the network and is slow).
        run: |
          MDBOOK_OUTPUT__HTML__SITE_URL="./" mdbook build
-          ./htmltest book --skip-external


Instead of using --skip-external, we now define CheckExternal: false in docs/.htmltest.yml

MadLittleMods · 2026-01-07T18:13:13Z

book.toml

 title = "Synapse"
 authors = ["The Matrix.org Foundation C.I.C."]
 language = "en"
-multilingual = false


Removed the book.multilingual field. This was never used. #2775

-- rust-lang/mdBook -> CHANGELOG.md -> 0.5 Migration Guide

MadLittleMods · 2026-01-07T18:14:00Z

scripts-dev/schema_versions.py

        context, book = json.load(sys.stdin)

-        for section in book["sections"]:
+        for section in book["items"]:


Renamed Book::sections to Book::items. #2813

-- rust-lang/mdBook -> CHANGELOG.md -> 0.5 Migration Guide

MadLittleMods · 2026-01-07T18:18:05Z

docs/website_files/theme/index.hbs

@@ -1,11 +1,11 @@
 <!DOCTYPE HTML>


Based off the standard template: crates/mdbook-html/front-end/templates/index.hbs

Our custom tweaks are labeled with 

.github/workflows/docs-pr.yaml

This PR contains the following updates: | Package | Update | Change | |---|---|---| | [element-hq/synapse](https://github.com/element-hq/synapse) | minor | `1.145.0` → `1.146.0` | --- > ⚠️ **Warning** > > Some dependencies could not be looked up. Check the Dependency Dashboard for more information. --- ### Release Notes <details> <summary>element-hq/synapse (element-hq/synapse)</summary> ### [`v1.146.0`](https://github.com/element-hq/synapse/releases/tag/v1.146.0) [Compare Source](element-hq/synapse@v1.145.0...v1.146.0rc1) ### Synapse 1.146.0 (2026-01-27) No significant changes since 1.146.0rc1. #### Deprecations and Removals - [MSC2697](matrix-org/matrix-spec-proposals#2697) (Dehydrated devices) has been removed, as the MSC is closed. Developers should migrate to [MSC3814](matrix-org/matrix-spec-proposals#3814). ([#19346](element-hq/synapse#19346)) - Support for Ubuntu 25.04 (Plucky Puffin) has been dropped. Synapse no longer builds debian packages for Ubuntu 25.04. ### Synapse 1.146.0rc1 (2026-01-20) #### Features - Add a new config option [`enable_local_media_storage`](https://element-hq.github.io/synapse/latest/usage/configuration/config_documentation.html#enable_local_media_storage) which controls whether media is additionally stored locally when using configured `media_storage_providers`. Setting this to `false` allows off-site media storage without a local cache. Contributed by Patrice Brend'amour [@dr](https://github.com/dr).allgood. ([#19204](element-hq/synapse#19204)) - Stabilise support for [MSC4312](matrix-org/matrix-spec-proposals#4312 `m.oauth` User-Interactive Auth stage for resetting cross-signing identity with the OAuth 2.0 API. The old, unstable name (`org.matrix.cross_signing_reset`) is now deprecated and will be removed in a future release. ([#19273](element-hq/synapse#19273)) - Refactor Grafana dashboard to use `server_name` label (instead of `instance`). ([#19337](element-hq/synapse#19337)) #### Bugfixes - Fix joining a restricted v12 room locally when no local room creator is present but local users with sufficient power levels are. Contributed by [@nexy7574](https://github.com/nexy7574). ([#19321](element-hq/synapse#19321)) - Fixed parallel calls to `/_matrix/media/v1/create` being ratelimited for appservices even if `rate_limited: false` was set in the registration. Contributed by [@tulir](https://github.com/tulir) @ Beeper. ([#19335](element-hq/synapse#19335)) - Fix a bug introduced in 1.61.0 where a user's membership in a room was accidentally ignored when considering access to historical state events in rooms with the "shared" history visibility. Contributed by Lukas Tautz. ([#19353](element-hq/synapse#19353)) - [MSC4140](matrix-org/matrix-spec-proposals#4140): Store the JSON content of scheduled delayed events as text instead of a byte array. This fixes the inability to schedule a delayed event with non-ASCII characters in its content. ([#19360](element-hq/synapse#19360)) - Always rollback database transactions when retrying (avoid orphaned connections). ([#19372](element-hq/synapse#19372)) - Fix `InFlightGauge` typing to allow upgrading to `prometheus_client` 0.24. ([#19379](element-hq/synapse#19379)) #### Updates to the Docker image - Add [Prometheus HTTP service discovery](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#http_sd_config) endpoint for easy discovery of all workers when using the `docker/Dockerfile-workers` image (see the [*Metrics* section of our Docker testing docs](docker/README-testing.md#metrics)). ([#19336](element-hq/synapse#19336)) #### Improved Documentation - Remove docs on legacy metric names (no longer in the codebase since 2022-12-06). ([#19341](element-hq/synapse#19341)) - Clarify how the estimated value of room complexity is calculated internally. ([#19384](element-hq/synapse#19384)) #### Internal Changes - Add an internal `cancel_task` API to the task scheduler. ([#19310](element-hq/synapse#19310)) - Tweak docstrings and signatures of `auth_types_for_event` and `get_catchup_room_event_ids`. ([#19320](element-hq/synapse#19320)) - Replace usage of deprecated `assertEquals` with `assertEqual` in unit test code. ([#19345](element-hq/synapse#19345)) - Drop support for Ubuntu 25.04 'Plucky Puffin', add support for Ubuntu 25.10 'Questing Quokka'. ([#19348](element-hq/synapse#19348)) - Revert "Add an Admin API endpoint for listing quarantined media ([#19268](element-hq/synapse#19268))". ([#19351](element-hq/synapse#19351)) - Bump `mdbook` from 0.4.17 to 0.5.2 and remove our custom table-of-contents plugin in favour of the new default functionality. ([#19356](element-hq/synapse#19356)) - Replace deprecated usage of PyGitHub's `GitRelease.title` with `.name` in release script. ([#19358](element-hq/synapse#19358)) - Update the Element logo in Synapse's README to be an absolute URL, allowing it to render on other sites (such as PyPI). ([#19368](element-hq/synapse#19368)) - Apply minor tweaks to v1.145.0 changelog. ([#19376](element-hq/synapse#19376)) - Update Grafana dashboard syntax to use the latest from importing/exporting with Grafana 12.3.1. ([#19381](element-hq/synapse#19381)) - Warn about skipping reactor metrics when using unknown reactor type. ([#19383](element-hq/synapse#19383)) - Add support for reactor metrics with the `ProxiedReactor` used in worker Complement tests. ([#19385](element-hq/synapse#19385)) </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever PR is behind base branch, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this PR, check this box --- This PR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).  Reviewed-on: https://gitea.alexlebens.dev/alexlebens/infrastructure/pulls/3533 Co-authored-by: Renovate Bot <renovate-bot@alexlebens.net> Co-committed-by: Renovate Bot <renovate-bot@alexlebens.net>

anoadragon453 added 7 commits January 7, 2026 14:41

Bump mdbook from 0.4.17 -> 0.5.2

f481991

The multilingual option was removed in 0.5, and never had any effect

8735831

See https://github.com/rust-lang/mdBook/blob/master/CHANGELOG.md#05-migration-guide

Remove custom table-of-contents mdbook plugin

8d4ff35

We can now rely on the default functionality built into mdbook for this.

Remove the remove-nav-buttons plugin

823338f

No longer needed as the original purpose was to stop them from interfering with the TOC on desktop.

Account for renamed list in mdbook JSON output

20b3842

"sections" was renamed to "items" in rust-lang/mdBook#2813

newsfile

e660cf2

anoadragon453 marked this pull request as ready for review January 7, 2026 16:31

anoadragon453 requested a review from a team as a code owner January 7, 2026 16:31

anoadragon453 added a commit that referenced this pull request Jan 7, 2026

Replace manual notes in documentation with admonitions

d3045cd

As they're generally prettier. Requires #19356

anoadragon453 mentioned this pull request Jan 7, 2026

Replace manual notes in documentation with admonitions #19357

Draft

3 tasks

devonh approved these changes Jan 7, 2026

View reviewed changes

MadLittleMods added the A-Docs label Jan 7, 2026

MadLittleMods reviewed Jan 7, 2026

View reviewed changes

anoadragon453 added 2 commits January 7, 2026 18:21

Empty print.html instead of deleting it.

5aa26fd

Make sure the file is still valid html (ugh)

57c8162

anoadragon453 enabled auto-merge (squash) January 7, 2026 18:25

MadLittleMods reviewed Jan 7, 2026

View reviewed changes

.github/workflows/docs-pr.yaml Outdated Show resolved Hide resolved

anoadragon453 disabled auto-merge January 7, 2026 18:32

Update the comments in CI

5f1fa3f

anoadragon453 enabled auto-merge (squash) January 7, 2026 18:33

anoadragon453 merged commit 1db2302 into develop Jan 7, 2026
37 checks passed

anoadragon453 deleted the anoa/update_mdbook branch January 7, 2026 18:46

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Bump mdbook from 0.4.17 -> 0.5.2 and remove custom table-of-contents plugin#19356

Bump mdbook from 0.4.17 -> 0.5.2 and remove custom table-of-contents plugin#19356
anoadragon453 merged 11 commits intodevelopfrom
anoa/update_mdbook

anoadragon453 commented Jan 7, 2026 •

edited by MadLittleMods

Loading

Uh oh!

devonh left a comment •

edited

Loading

Uh oh!

MadLittleMods Jan 7, 2026

Uh oh!

anoadragon453 Jan 7, 2026 •

edited by MadLittleMods

Loading

Uh oh!

anoadragon453 Jan 7, 2026

Uh oh!

MadLittleMods Jan 7, 2026

Uh oh!

MadLittleMods Jan 7, 2026

Uh oh!

MadLittleMods Jan 7, 2026

Uh oh!

MadLittleMods Jan 7, 2026

Uh oh!

MadLittleMods Jan 7, 2026

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		# Don't check external links, as that requires network access and is slow.
		CheckExternal: false No newline at end of file

Conversation

anoadragon453 commented Jan 7, 2026 • edited by MadLittleMods Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Checklist

Uh oh!

devonh left a comment • 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!

MadLittleMods Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

anoadragon453 Jan 7, 2026 • edited by MadLittleMods Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anoadragon453 Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

MadLittleMods Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

MadLittleMods Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

MadLittleMods Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

MadLittleMods Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

MadLittleMods Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

anoadragon453 commented Jan 7, 2026 •

edited by MadLittleMods

Loading

devonh left a comment •

edited

Loading

anoadragon453 Jan 7, 2026 •

edited by MadLittleMods

Loading