diff --git a/.github/workflows/docs-pr.yaml b/.github/workflows/docs-pr.yaml
index eed2acc4a9..4480fd80bc 100644
--- a/.github/workflows/docs-pr.yaml
+++ b/.github/workflows/docs-pr.yaml
@@ -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
@@ -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'
- name: Setup htmltest
run: |
@@ -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
+
+ # 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 '' > book/print.html
+
+ ./htmltest book --conf docs/.htmltest.yml
diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
index e33add1830..d64adf924c 100644
--- a/.github/workflows/docs.yaml
+++ b/.github/workflows/docs.yaml
@@ -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
diff --git a/book.toml b/book.toml
index 98d749ed39..99e4d03bf4 100644
--- a/book.toml
+++ b/book.toml
@@ -4,7 +4,6 @@
title = "Synapse"
authors = ["The Matrix.org Foundation C.I.C."]
language = "en"
-multilingual = false
# The directory that documentation files are stored in
src = "docs"
@@ -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",
]
diff --git a/changelog.d/19356.misc b/changelog.d/19356.misc
new file mode 100644
index 0000000000..3b9d16a380
--- /dev/null
+++ b/changelog.d/19356.misc
@@ -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.
\ No newline at end of file
diff --git a/docs/.htmltest.yml b/docs/.htmltest.yml
new file mode 100644
index 0000000000..59d34ce0a0
--- /dev/null
+++ b/docs/.htmltest.yml
@@ -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
\ No newline at end of file
diff --git a/docs/website_files/README.md b/docs/website_files/README.md
index bc51c4865e..b5521997d5 100644
--- a/docs/website_files/README.md
+++ b/docs/website_files/README.md
@@ -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).
\ No newline at end of file
+[customising the default themes](https://rust-lang.github.io/mdBook/format/theme/index.html).
diff --git a/docs/website_files/remove-nav-buttons.css b/docs/website_files/remove-nav-buttons.css
deleted file mode 100644
index 4b280794ea..0000000000
--- a/docs/website_files/remove-nav-buttons.css
+++ /dev/null
@@ -1,8 +0,0 @@
-/* Remove the prev, next chapter buttons as they interfere with the
- * table of contents.
- * Note that the table of contents only appears on desktop, thus we
- * only remove the desktop (wide) chapter buttons.
- */
-.nav-wide-wrapper {
- display: none
-}
\ No newline at end of file
diff --git a/docs/website_files/table-of-contents.css b/docs/website_files/table-of-contents.css
deleted file mode 100644
index 1b6f44b66a..0000000000
--- a/docs/website_files/table-of-contents.css
+++ /dev/null
@@ -1,47 +0,0 @@
-:root {
- --pagetoc-width: 250px;
-}
-
-@media only screen and (max-width:1439px) {
- .sidetoc {
- display: none;
- }
-}
-
-@media only screen and (min-width:1440px) {
- main {
- position: relative;
- margin-left: 100px !important;
- margin-right: var(--pagetoc-width) !important;
- }
- .sidetoc {
- margin-left: auto;
- margin-right: auto;
- left: calc(100% + (var(--content-max-width))/4 - 140px);
- position: absolute;
- text-align: right;
- }
- .pagetoc {
- position: fixed;
- width: var(--pagetoc-width);
- overflow: auto;
- right: 20px;
- height: calc(100% - var(--menu-bar-height));
- }
- .pagetoc a {
- color: var(--fg) !important;
- display: block;
- padding: 5px 15px 5px 10px;
- text-align: left;
- text-decoration: none;
- }
- .pagetoc a:hover,
- .pagetoc a.active {
- background: var(--sidebar-bg) !important;
- color: var(--sidebar-fg) !important;
- }
- .pagetoc .active {
- background: var(--sidebar-bg);
- color: var(--sidebar-fg);
- }
-}
diff --git a/docs/website_files/table-of-contents.js b/docs/website_files/table-of-contents.js
deleted file mode 100644
index 772da97fb9..0000000000
--- a/docs/website_files/table-of-contents.js
+++ /dev/null
@@ -1,148 +0,0 @@
-const getPageToc = () => document.getElementsByClassName('pagetoc')[0];
-
-const pageToc = getPageToc();
-const pageTocChildren = [...pageToc.children];
-const headers = [...document.getElementsByClassName('header')];
-
-
-// Select highlighted item in ToC when clicking an item
-pageTocChildren.forEach(child => {
- child.addEventHandler('click', () => {
- pageTocChildren.forEach(child => {
- child.classList.remove('active');
- });
- child.classList.add('active');
- });
-});
-
-
-/**
- * Test whether a node is in the viewport
- */
-function isInViewport(node) {
- const rect = node.getBoundingClientRect();
- return rect.top >= 0 && rect.left >= 0 && rect.bottom <= (window.innerHeight || document.documentElement.clientHeight) && rect.right <= (window.innerWidth || document.documentElement.clientWidth);
-}
-
-
-/**
- * Set a new ToC entry.
- * Clear any previously highlighted ToC items, set the new one,
- * and adjust the ToC scroll position.
- */
-function setTocEntry() {
- let activeEntry;
- const pageTocChildren = [...getPageToc().children];
-
- // Calculate which header is the current one at the top of screen
- headers.forEach(header => {
- if (window.pageYOffset >= header.offsetTop) {
- activeEntry = header;
- }
- });
-
- // Update selected item in ToC when scrolling
- pageTocChildren.forEach(child => {
- if (activeEntry.href.localeCompare(child.href) === 0) {
- child.classList.add('active');
- } else {
- child.classList.remove('active');
- }
- });
-
- let tocEntryForLocation = document.querySelector(`nav a[href="${activeEntry.href}"]`);
- if (tocEntryForLocation) {
- const headingForLocation = document.querySelector(activeEntry.hash);
- if (headingForLocation && isInViewport(headingForLocation)) {
- // Update ToC scroll
- const nav = getPageToc();
- const content = document.querySelector('html');
- if (content.scrollTop !== 0) {
- nav.scrollTo({
- top: tocEntryForLocation.offsetTop - 100,
- left: 0,
- behavior: 'smooth',
- });
- } else {
- nav.scrollTop = 0;
- }
- }
- }
-}
-
-
-/**
- * Populate sidebar on load
- */
-window.addEventListener('load', () => {
- // Prevent rendering the table of contents of the "print book" page, as it
- // will end up being rendered into the output (in a broken-looking way)
-
- // Get the name of the current page (i.e. 'print.html')
- const pageNameExtension = window.location.pathname.split('/').pop();
-
- // Split off the extension (as '.../print' is also a valid page name), which
- // should result in 'print'
- const pageName = pageNameExtension.split('.')[0];
- if (pageName === "print") {
- // Don't render the table of contents on this page
- return;
- }
-
- // Only create table of contents if there is more than one header on the page
- if (headers.length <= 1) {
- return;
- }
-
- // Create an entry in the page table of contents for each header in the document
- headers.forEach((header, index) => {
- const link = document.createElement('a');
-
- // Indent shows hierarchy
- let indent = '0px';
- switch (header.parentElement.tagName) {
- case 'H1':
- indent = '5px';
- break;
- case 'H2':
- indent = '20px';
- break;
- case 'H3':
- indent = '30px';
- break;
- case 'H4':
- indent = '40px';
- break;
- case 'H5':
- indent = '50px';
- break;
- case 'H6':
- indent = '60px';
- break;
- default:
- break;
- }
-
- let tocEntry;
- if (index == 0) {
- // Create a bolded title for the first element
- tocEntry = document.createElement("strong");
- tocEntry.innerHTML = header.text;
- } else {
- // All other elements are non-bold
- tocEntry = document.createTextNode(header.text);
- }
- link.appendChild(tocEntry);
-
- link.style.paddingLeft = indent;
- link.href = header.href;
- pageToc.appendChild(link);
- });
- setTocEntry.call();
-});
-
-
-// Handle active headers on scroll, if there is more than one header on the page
-if (headers.length > 1) {
- window.addEventListener('scroll', setTocEntry);
-}
diff --git a/docs/website_files/theme/index.hbs b/docs/website_files/theme/index.hbs
index 9cf7521e80..3126184c9b 100644
--- a/docs/website_files/theme/index.hbs
+++ b/docs/website_files/theme/index.hbs
@@ -1,11 +1,11 @@
-
+
{{ title }}
{{#if is_print }}
-
+
{{/if}}
{{#if base_url}}
@@ -15,60 +15,78 @@
{{> head}}
-
-
+
{{#if favicon_svg}}
-
+
{{/if}}
{{#if favicon_png}}
-
+
{{/if}}
-
-
-
+
+
+
{{#if print_enable}}
-
+
{{/if}}
-
- {{#if copy_fonts}}
-
- {{/if}}
+
-
-
-
+
+
+
{{#each additional_css}}
-
+
{{/each}}
{{#if mathjax_support}}
-
+
{{/if}}
+
+
+
+
+
-
-
-
+