diff --git a/book.toml b/book.toml
index b21b647526..8d72082c88 100644
--- a/book.toml
+++ b/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"
\ No newline at end of file
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index e94c84ce27..7c8c943f32 100644
--- a/docs/SUMMARY.md
+++ b/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)
\ No newline at end of file
diff --git a/docs/website_files/README.md b/docs/website_files/README.md
index acf73350d6..04d191479b 100644
--- a/docs/website_files/README.md
+++ b/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)
diff --git a/docs/website_files/indent-section-headers.css b/docs/website_files/indent-section-headers.css
new file mode 100644
index 0000000000..f9b3c82ca6
--- /dev/null
+++ b/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;
+}
\ No newline at end of file
|
