Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
anoadragon453 merged 11 commits into from
Jan 7, 2026
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
f481991
Bump `mdbook` from 0.4.17 -> 0.5.2
anoadragon453 Jan 7, 2026
8735831
The `multilingual` option was removed in 0.5, and never had any effect
anoadragon453 Jan 7, 2026
8d4ff35
Remove custom table-of-contents mdbook plugin
anoadragon453 Jan 7, 2026
4c807ca
Port new changes to mdbook default theme to our copy
anoadragon453 Jan 7, 2026
823338f
Remove the remove-nav-buttons plugin
anoadragon453 Jan 7, 2026
20b3842
Account for renamed list in mdbook JSON output
anoadragon453 Jan 7, 2026
e660cf2
newsfile
anoadragon453 Jan 7, 2026
84ed978
Prevent `htmltest` from checking `print.html`
anoadragon453 Jan 7, 2026
5aa26fd
Empty `print.html` instead of deleting it.
anoadragon453 Jan 7, 2026
57c8162
Make sure the file is still valid html (ugh)
anoadragon453 Jan 7, 2026
5f1fa3f
Update the comments in CI
anoadragon453 Jan 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 14 additions & 5 deletions .github/workflows/docs-pr.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ jobs:
- name: Setup mdbook
uses: peaceiris/actions-mdbook@ee69d230fe19748b7abf22df32acaa93833fad08 # v2.0.0
with:
mdbook-version: '0.4.17'
mdbook-version: '0.5.2'

- name: Setup python
uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
Expand Down Expand Up @@ -55,7 +55,7 @@ jobs:
- name: Setup mdbook
uses: peaceiris/actions-mdbook@ee69d230fe19748b7abf22df32acaa93833fad08 # v2.0.0
with:
mdbook-version: '0.4.17'
mdbook-version: '0.5.2'
Copy link
Copy Markdown
Contributor

@MadLittleMods MadLittleMods Jan 7, 2026

Choose a reason for hiding this comment

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

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

Copy link
Copy Markdown
Member Author

@anoadragon453 anoadragon453 Jan 7, 2026 •
edited by MadLittleMods
Loading

Choose a reason for hiding this comment

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

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...

Copy link
Copy Markdown
Member Author

@anoadragon453 anoadragon453 Jan 7, 2026

Choose a reason for hiding this comment

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

Have done the workaround and left a sad comment.


- name: Setup htmltest
run: |
Expand All @@ -64,8 +64,17 @@ jobs:
tar zxf htmltest_0.17.0_linux_amd64.tar.gz

- name: Test links with htmltest
# Build the book with `./` as the site URL (to make checks on 404.html possible)
# Then run htmltest (without checking external links since that involves the network and is slow).
run: |
# Build the book with `./` as the site URL (to make checks on 404.html possible)
MDBOOK_OUTPUT__HTML__SITE_URL="./" mdbook build
./htmltest book --skip-external
Copy link
Copy Markdown
Contributor

@MadLittleMods MadLittleMods Jan 7, 2026

Choose a reason for hiding this comment

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

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


# Delete the contents of the print.html file, as it can raise false
# positives during link checking.
#
# We empty out the file, instead of deleting it, as doing so would
# just cause htmltest to complain that links to it were invalid.
# Ideally `htmltest` would have an option to ignore specific files
# instead.
echo '<!DOCTYPE HTML>' > book/print.html

./htmltest book --conf docs/.htmltest.yml
2 changes: 1 addition & 1 deletion .github/workflows/docs.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ jobs:
- name: Setup mdbook
uses: peaceiris/actions-mdbook@ee69d230fe19748b7abf22df32acaa93833fad08 # v2.0.0
with:
mdbook-version: '0.4.17'
mdbook-version: '0.5.2'

- name: Set version of docs
run: echo 'window.SYNAPSE_VERSION = "${{ needs.pre.outputs.branch-version }}";' > ./docs/website_files/version.js
Expand Down
4 changes: 0 additions & 4 deletions book.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,6 @@
title = "Synapse"
authors = ["The Matrix.org Foundation C.I.C."]
language = "en"
multilingual = false
Copy link
Copy Markdown
Contributor

@MadLittleMods MadLittleMods Jan 7, 2026

Choose a reason for hiding this comment

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

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

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


# The directory that documentation files are stored in
src = "docs"
Expand All @@ -31,13 +30,10 @@ site-url = "/synapse/"
# Additional HTML, JS, CSS that's injected into each page of the book.
# More information available in docs/website_files/README.md
additional-css = [
"docs/website_files/table-of-contents.css",
"docs/website_files/remove-nav-buttons.css",
"docs/website_files/indent-section-headers.css",
"docs/website_files/version-picker.css",
]
additional-js = [
"docs/website_files/table-of-contents.js",
"docs/website_files/version-picker.js",
"docs/website_files/version.js",
]
Expand Down
1 change: 1 addition & 0 deletions changelog.d/19356.misc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
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.
5 changes: 5 additions & 0 deletions docs/.htmltest.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# Configuration for htmltest, which we run in CI to check that links aren't broken in the built documentation.
# See all config options: https://github.com/wjdp/htmltest#wrench-configuration

# Don't check external links, as that requires network access and is slow.
CheckExternal: false
Comment on lines +4 to +5
Copy link
Copy Markdown
Contributor

@MadLittleMods MadLittleMods Jan 7, 2026

Choose a reason for hiding this comment

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

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

27 changes: 9 additions & 18 deletions docs/website_files/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,27 +9,18 @@ point to additional JS/CSS in this directory that are added on each page load. I
addition, the `theme` directory contains files that overwrite their counterparts in
each of the default themes included with mdbook.

Currently we use these files to generate a floating Table of Contents panel. The code for
which was partially taken from
[JorelAli/mdBook-pagetoc](https://github.com/JorelAli/mdBook-pagetoc/)
before being modified such that it scrolls with the content of the page. This is handled
by the `table-of-contents.js/css` files. The table of contents panel only appears on pages
that have more than one header, as well as only appearing on desktop-sized monitors.
Currently we use these files to make a few modifications:

We remove the navigation arrows which typically appear on the left and right side of the
screen on desktop as they interfere with the table of contents. This is handled by
the `remove-nav-buttons.css` file.
* We stylise the chapter titles in the left sidebar by indenting them
slightly so that they are more visually distinguishable from the section headers
(the bold titles). This is done through the `indent-section-headers.css` file.

Finally, we also stylise the chapter titles in the left sidebar by indenting them
slightly so that they are more visually distinguishable from the section headers
(the bold titles). This is done through the `indent-section-headers.css` file.

In addition to these modifications, we have added a version picker to the documentation.
Users can switch between documentations for different versions of Synapse.
This functionality was implemented through the `version-picker.js` and
`version-picker.css` files.
* We add a version picker pertaining to the different documentation versions
shipped with each version of Synapse. This functionality was implemented through
the `version-picker.js` and `version-picker.css` files, and is currently the only
requirement for the custom `theme/`.

More information can be found in mdbook's official documentation for
[injecting page JS/CSS](https://rust-lang.github.io/mdBook/format/config.html)
and
[customising the default themes](https://rust-lang.github.io/mdBook/format/theme/index.html).
[customising the default themes](https://rust-lang.github.io/mdBook/format/theme/index.html).
8 changes: 0 additions & 8 deletions docs/website_files/remove-nav-buttons.css
View file
Open in desktop

This file was deleted.

47 changes: 0 additions & 47 deletions docs/website_files/table-of-contents.css
View file
Open in desktop

This file was deleted.

148 changes: 0 additions & 148 deletions docs/website_files/table-of-contents.js
View file
Open in desktop

This file was deleted.

Loading