Refine the sidebar: switch to headers without labels

This just ends up looking much cleaner.

Also includes some updates to the description of what each custom
JS/CSS file does.

book.toml

@@ -19,6 +19,10 @@ create-missing = false
 # Disabled until https://github.com/rust-lang/mdBook/issues/1543 is fixed
 #edit-url-template = "https://github.com/matrix-org/synapse/edit/develop/{path}"
 
+# Remove the numbers that appear before each item in the sidebar, as they can
+# get quite messy as we nest deeper
+no-section-label = true
+
 # The source code URL of the repository
 git-repository-url = "https://github.com/matrix-org/synapse"
 
@@ -26,7 +30,11 @@ git-repository-url = "https://github.com/matrix-org/synapse"
 site-url = "/synapse/"
 
 # Additional HTML, JS, CSS that's injected into each page of the book.
-# More information is available in docs/website_files/README.md
-additional-css = ["docs/website_files/table-of-contents.css", "docs/website_files/remove-nav-buttons.css"]
+# 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",
+]
 additional-js = ["docs/website_files/table-of-contents.js"]
 theme = "docs/website_files/theme"

docs/SUMMARY.md

@@ -1,15 +1,20 @@
 # Summary
 
-- [Introduction](welcome_and_overview.md)
-- [Setup](setup/README.md)
+# Introduction
+- [Welcome and Overview](welcome_and_overview.md)
+
+# Setup
   - [Installation](setup/installation.md)
   - [Using Postgres](postgres.md)
   - [Configuring a Reverse Proxy](reverse_proxy.md)
   - [Configuring a Turn Server](turn-howto.md)
   - [Delegation](delegate.md)
-- [Upgrading](upgrading/README.md)
+
+# Upgrading
+  - [Upgrading between Synapse Versions](upgrading/README.md)
   - [Upgrading from pre-Synapse 1.0](MSC1711_certificates_FAQ.md)
-- [Usage](usage/README.md)
+
+# Usage
   - [Federation](federate.md)
   - [Configuration](usage/configuration/README.md)
     - [Sample Configuration Files](usage/configuration/sample_config.md)
@@ -36,27 +41,29 @@
     - [Workers](workers.md)
       - [Using `synctl` with Workers](synctl_workers.md)
       - [Systemd](systemd-with-workers/README.md)
-  - [Administration](usage/administration/README.md)
-    - [Admin API](usage/administration/admin_api/README.md)
-      - [Account Validity](admin_api/account_validity.rst)
-      - [Delete Group](admin_api/delete_group.md)
-      - [Event Reports](admin_api/event_reports.md)
-      - [Media](admin_api/media_admin_api.md)
-      - [Purge History](admin_api/purge_history_api.rst)
-      - [Purge Rooms](admin_api/purge_room.md)
-      - [Register Users](admin_api/register_api.rst)
-      - [Manipulate Room Membership](admin_api/room_membership.md)
-      - [Rooms](admin_api/rooms.md)
-      - [Server Notices](admin_api/server_notices.md)
-      - [Shutdown Room](admin_api/shutdown_room.md)
-      - [Statistics](admin_api/statistics.md)
-      - [Users](admin_api/user_admin_api.rst)
-      - [Server Version](admin_api/version_api.rst)
-    - [Manhole](manhole.md)
-    - [Monitoring](metrics-howto.md)
-    - [Structured Logging](structured_logging.md)
-    - [Scripts]()
-- [Development](development/README.md)
+
+# Administration
+  - [Admin API](usage/administration/admin_api/README.md)
+    - [Account Validity](admin_api/account_validity.rst)
+    - [Delete Group](admin_api/delete_group.md)
+    - [Event Reports](admin_api/event_reports.md)
+    - [Media](admin_api/media_admin_api.md)
+    - [Purge History](admin_api/purge_history_api.rst)
+    - [Purge Rooms](admin_api/purge_room.md)
+    - [Register Users](admin_api/register_api.rst)
+    - [Manipulate Room Membership](admin_api/room_membership.md)
+    - [Rooms](admin_api/rooms.md)
+    - [Server Notices](admin_api/server_notices.md)
+    - [Shutdown Room](admin_api/shutdown_room.md)
+    - [Statistics](admin_api/statistics.md)
+    - [Users](admin_api/user_admin_api.rst)
+    - [Server Version](admin_api/version_api.rst)
+  - [Manhole](manhole.md)
+  - [Monitoring](metrics-howto.md)
+  - [Structured Logging](structured_logging.md)
+  - [Scripts]()
+
+# Development
   - [Contributing Guide](development/contributing_guide.md)
   - [Code Style](code_style.md)
   - [Git Usage](dev/git.md)
@@ -75,5 +82,6 @@
     - [Media Repository](media_repository.md)
     - [Room and User Statistics](room_and_user_statistics.md)
   - [Scripts]()
-- [Other](other/README.md)
+
+# Other
   - [Dependency Deprecation Policy](deprecation_policy.md)

docs/website_files/README.md

@@ -9,10 +9,20 @@ 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 page.
-The code for which was partially taken from
+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.
+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.
+
+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.
+
+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.
 
 More information can be found in mdbook's official documentation for
 [injecting page JS/CSS](https://rust-lang.github.io/mdBook/format/config.html)

docs/website_files/indent-section-headers.css

@@ -0,0 +1,7 @@
+/*
+ * Indents each chapter title in the left sidebar so that they aren't
+ * at the same level as the section headers.
+ */
+.chapter-item {
+    margin-left: 1em;
+}