diff --git a/docs/book.toml b/docs/book.toml
index 98085c0cfa..70e294c014 100644
--- a/docs/book.toml
+++ b/docs/book.toml
@@ -15,37 +15,57 @@ additional-js  = ["theme/page-toc.js", "theme/plugins.js"]
 [output.html.print]
 enable = false
 
+# Redirects for `/docs` pages.
+#
+# All of the source URLs are interpreted relative to mdBook, so they must:
+# 1. Not start with `/docs`
+# 2. End in `.html`
+#
+# The destination URLs are interpreted relative to `https://zed.dev`.
+# - Redirects to other docs pages should end in `.html`
+# - You can link to pages on the Zed site by omitting the `/docs` in front of it.
 [output.html.redirect]
-"/elixir.html" = "/docs/languages/elixir.html"
-"/javascript.html" = "/docs/languages/javascript.html"
-"/ruby.html" = "/docs/languages/ruby.html"
-"/python.html" = "/docs/languages/python.html"
-"/adding-new-languages.html" = "/docs/extensions/languages.html"
-"/language-model-integration.html" = "/docs/assistant/assistant.html"
-"/assistant.html" = "/docs/assistant/assistant.html"
-"/developing-zed.html" = "/docs/development.html"
-"/conversations.html" = "/community-links"
+# AI
 "/ai.html" = "/docs/ai/overview.html"
-"/assistant/assistant.html" = "/docs/ai/overview.html"
-"/assistant/configuration.html" = "/docs/ai/configuration.html"
+"/assistant-panel.html" = "/docs/ai/agent-panel.html"
+"/assistant.html" = "/docs/assistant/assistant.html"
 "/assistant/assistant-panel.html" = "/docs/ai/agent-panel.html"
+"/assistant/assistant.html" = "/docs/ai/overview.html"
+"/assistant/commands.html" = "/docs/ai/text-threads.html"
+"/assistant/configuration.html" = "/docs/ai/configuration.html"
+"/assistant/context-servers.html" = "/docs/ai/mcp.html"
 "/assistant/contexts.html" = "/docs/ai/text-threads.html"
 "/assistant/inline-assistant.html" = "/docs/ai/inline-assistant.html"
-"/assistant/commands.html" = "/docs/ai/text-threads.html"
-"/assistant/prompting.html" = "/docs/ai/rules.html"
-"/assistant/context-servers.html" = "/docs/ai/mcp.html"
 "/assistant/model-context-protocol.html" = "/docs/ai/mcp.html"
+"/assistant/prompting.html" = "/docs/ai/rules.html"
+"/language-model-integration.html" = "/docs/assistant/assistant.html"
 "/model-improvement.html" = "/docs/ai/ai-improvement.html"
-"/extensions/context-servers.html" = "/docs/extensions/mcp-extensions.html"
-"/assistant-panel.html" = "/docs/ai/agent-panel.html"
-"/assistant/model-context-protocolCitedby.html" = "/docs/ai/mcp.html"
+
+# Community
 "/community/feedback.html" = "/community-links"
+"/conversations.html" = "/community-links"
+
+# Debugger
+"/debuggers.html" = "/docs/debugger.html"
+
+# MCP
+"/assistant/model-context-protocolCitedby.html" = "/docs/ai/mcp.html"
 "/context-servers.html" = "/docs/ai/mcp.html"
+"/extensions/context-servers.html" = "/docs/extensions/mcp-extensions.html"
+
+# Languages
+"/adding-new-languages.html" = "/docs/extensions/languages.html"
+"/elixir.html" = "/docs/languages/elixir.html"
+"/javascript.html" = "/docs/languages/javascript.html"
+"/python.html" = "/docs/languages/python.html"
+"/ruby.html" = "/docs/languages/ruby.html"
+
+# Zed development
 "/contribute-to-zed.html" = "/docs/development.html#contributor-links"
 "/contributing.html" = "/docs/development.html#contributor-links"
-"/debuggers.html" = "/docs/debugger.html"
-"/development/development/macos.html" = "/docs/development/macos.html"
+"/developing-zed.html" = "/docs/development.html"
 "/development/development/linux.html" = "/docs/development/linux.html"
+"/development/development/macos.html" = "/docs/development/macos.html"
 "/development/development/windows.html" = "/docs/development/windows.html"
 
 # Our custom preprocessor for expanding commands like `{#kb action::ActionName}`,