diff options
author | Andrew Morgan <andrew@amorgan.xyz> | 2021-05-26 19:29:21 +0100 |
---|---|---|
committer | Andrew Morgan <andrew@amorgan.xyz> | 2021-05-27 18:40:24 +0100 |
commit | d042d8425bd51748831138ff9db91faec38a2fc3 (patch) | |
tree | 1a082b6727ec2123dbb4983fe2fb1f55a5c1275a | |
parent | Update oft-linked to admin_api directory with info about the new site (diff) | |
download | synapse-d042d8425bd51748831138ff9db91faec38a2fc3.tar.xz |
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.
-rw-r--r-- | book.toml | 12 | ||||
-rw-r--r-- | docs/SUMMARY.md | 60 | ||||
-rw-r--r-- | docs/website_files/README.md | 16 | ||||
-rw-r--r-- | docs/website_files/indent-section-headers.css | 7 |
4 files changed, 64 insertions, 31 deletions
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 |