Skip to content

Commit 1db2302

Browse files
anoadragon453anoadragon453
authored
Bump mdbook from 0.4.17 -> 0.5.2 and remove custom table-of-contents plugin (#19356)
1 parent 8ff1960 commit 1db2302

File tree

11 files changed

+229
-372
lines changed

11 files changed

+229
-372
lines changed

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

Lines changed: 14 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ jobs:
2121
- name: Setup mdbook
2222
uses: peaceiris/actions-mdbook@ee69d230fe19748b7abf22df32acaa93833fad08 # v2.0.0
2323
with:
24-
mdbook-version: '0.4.17'
24+
mdbook-version: '0.5.2'
2525

2626
- name: Setup python
2727
uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
@@ -55,7 +55,7 @@ jobs:
5555
- name: Setup mdbook
5656
uses: peaceiris/actions-mdbook@ee69d230fe19748b7abf22df32acaa93833fad08 # v2.0.0
5757
with:
58-
mdbook-version: '0.4.17'
58+
mdbook-version: '0.5.2'
5959

6060
- name: Setup htmltest
6161
run: |
@@ -64,8 +64,17 @@ jobs:
6464
tar zxf htmltest_0.17.0_linux_amd64.tar.gz
6565
6666
- name: Test links with htmltest
67-
# Build the book with `./` as the site URL (to make checks on 404.html possible)
68-
# Then run htmltest (without checking external links since that involves the network and is slow).
6967
run: |
68+
# Build the book with `./` as the site URL (to make checks on 404.html possible)
7069
MDBOOK_OUTPUT__HTML__SITE_URL="./" mdbook build
71-
./htmltest book --skip-external
70+
71+
# Delete the contents of the print.html file, as it can raise false
72+
# positives during link checking.
73+
#
74+
# We empty out the file, instead of deleting it, as doing so would
75+
# just cause htmltest to complain that links to it were invalid.
76+
# Ideally `htmltest` would have an option to ignore specific files
77+
# instead.
78+
echo '<!DOCTYPE HTML>' > book/print.html
79+
80+
./htmltest book --conf docs/.htmltest.yml

‎.github/workflows/docs.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,7 @@ jobs:
5858
- name: Setup mdbook
5959
uses: peaceiris/actions-mdbook@ee69d230fe19748b7abf22df32acaa93833fad08 # v2.0.0
6060
with:
61-
mdbook-version: '0.4.17'
61+
mdbook-version: '0.5.2'
6262

6363
- name: Set version of docs
6464
run: echo 'window.SYNAPSE_VERSION = "${{ needs.pre.outputs.branch-version }}";' > ./docs/website_files/version.js

‎book.toml‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,6 @@
44
title = "Synapse"
55
authors = ["The Matrix.org Foundation C.I.C."]
66
language = "en"
7-
multilingual = false
87

98
# The directory that documentation files are stored in
109
src = "docs"
@@ -31,13 +30,10 @@ site-url = "/synapse/"
3130
# Additional HTML, JS, CSS that's injected into each page of the book.
3231
# More information available in docs/website_files/README.md
3332
additional-css = [
34-
"docs/website_files/table-of-contents.css",
35-
"docs/website_files/remove-nav-buttons.css",
3633
"docs/website_files/indent-section-headers.css",
3734
"docs/website_files/version-picker.css",
3835
]
3936
additional-js = [
40-
"docs/website_files/table-of-contents.js",
4137
"docs/website_files/version-picker.js",
4238
"docs/website_files/version.js",
4339
]

‎changelog.d/19356.misc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
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.

‎docs/.htmltest.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Configuration for htmltest, which we run in CI to check that links aren't broken in the built documentation.
2+
# See all config options: https://github.com/wjdp/htmltest#wrench-configuration
3+
4+
# Don't check external links, as that requires network access and is slow.
5+
CheckExternal: false

‎docs/website_files/README.md‎

Lines changed: 9 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -9,27 +9,18 @@ point to additional JS/CSS in this directory that are added on each page load. I
99
addition, the `theme` directory contains files that overwrite their counterparts in
1010
each of the default themes included with mdbook.
1111

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

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

23-
Finally, we also stylise the chapter titles in the left sidebar by indenting them
24-
slightly so that they are more visually distinguishable from the section headers
25-
(the bold titles). This is done through the `indent-section-headers.css` file.
26-
27-
In addition to these modifications, we have added a version picker to the documentation.
28-
Users can switch between documentations for different versions of Synapse.
29-
This functionality was implemented through the `version-picker.js` and
30-
`version-picker.css` files.
18+
* We add a version picker pertaining to the different documentation versions
19+
shipped with each version of Synapse. This functionality was implemented through
20+
the `version-picker.js` and `version-picker.css` files, and is currently the only
21+
requirement for the custom `theme/`.
3122

3223
More information can be found in mdbook's official documentation for
3324
[injecting page JS/CSS](https://rust-lang.github.io/mdBook/format/config.html)
3425
and
35-
[customising the default themes](https://rust-lang.github.io/mdBook/format/theme/index.html).
26+
[customising the default themes](https://rust-lang.github.io/mdBook/format/theme/index.html).

‎docs/website_files/remove-nav-buttons.css‎

Lines changed: 0 additions & 8 deletions
This file was deleted.

‎docs/website_files/table-of-contents.css‎

Lines changed: 0 additions & 47 deletions
This file was deleted.

‎docs/website_files/table-of-contents.js‎

Lines changed: 0 additions & 148 deletions
This file was deleted.

0 commit comments

Comments
 (0)