docs: serve package reference pages at folder URLs

Rename each generated package __init__.md to index.md and rewrite the generated sidebar.json edges to match. The docusaurus renderer emits a package's docs as <pkg>/__init__.md, whose route is .../<pkg>/__init__ -- nothing resolves at the bare .../<pkg>/ URL that the sidebar's Reference link (.../reference/slack_bolt/) targets. Docusaurus serves index.md at the folder URL, so this makes that link resolve instead of 404. Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>
lukegalbraithrussell · Aug 13, 2026 · Aug 13, 2026 · Aug 13, 2026 · Aug 13, 2026 · Aug 13, 2026
commit 2266bf27f12f7b79b887957a75990589fa1d1e1d
diff --git a/docs/reference/sidebar.json b/docs/reference/sidebar.json
diff --git a/...ce/slack_bolt/adapter/aiohttp/__init__.md → ...rence/slack_bolt/adapter/aiohttp/index.md b/...ce/slack_bolt/adapter/aiohttp/__init__.md → ...rence/slack_bolt/adapter/aiohttp/index.md
diff --git a/...ack_bolt/adapter/asgi/aiohttp/__init__.md → .../slack_bolt/adapter/asgi/aiohttp/index.md b/...ack_bolt/adapter/asgi/aiohttp/__init__.md → .../slack_bolt/adapter/asgi/aiohttp/index.md
diff --git a/...ack_bolt/adapter/asgi/builtin/__init__.md → .../slack_bolt/adapter/asgi/builtin/index.md b/...ack_bolt/adapter/asgi/builtin/__init__.md → .../slack_bolt/adapter/asgi/builtin/index.md
diff --git a/...rence/slack_bolt/adapter/asgi/__init__.md → ...eference/slack_bolt/adapter/asgi/index.md b/...rence/slack_bolt/adapter/asgi/__init__.md → ...eference/slack_bolt/adapter/asgi/index.md
diff --git a/...slack_bolt/adapter/aws_lambda/__init__.md → ...ce/slack_bolt/adapter/aws_lambda/index.md b/...slack_bolt/adapter/aws_lambda/__init__.md → ...ce/slack_bolt/adapter/aws_lambda/index.md
diff --git a/...nce/slack_bolt/adapter/bottle/__init__.md → ...erence/slack_bolt/adapter/bottle/index.md b/...nce/slack_bolt/adapter/bottle/__init__.md → ...erence/slack_bolt/adapter/bottle/index.md
diff --git a/...e/slack_bolt/adapter/cherrypy/__init__.md → ...ence/slack_bolt/adapter/cherrypy/index.md b/...e/slack_bolt/adapter/cherrypy/__init__.md → ...ence/slack_bolt/adapter/cherrypy/index.md
diff --git a/...nce/slack_bolt/adapter/django/__init__.md → ...erence/slack_bolt/adapter/django/index.md b/...nce/slack_bolt/adapter/django/__init__.md → ...erence/slack_bolt/adapter/django/index.md
diff --git a/...nce/slack_bolt/adapter/falcon/__init__.md → ...erence/slack_bolt/adapter/falcon/index.md b/...nce/slack_bolt/adapter/falcon/__init__.md → ...erence/slack_bolt/adapter/falcon/index.md
diff --git a/...ce/slack_bolt/adapter/fastapi/__init__.md → ...rence/slack_bolt/adapter/fastapi/index.md b/...ce/slack_bolt/adapter/fastapi/__init__.md → ...rence/slack_bolt/adapter/fastapi/index.md
diff --git a/...ence/slack_bolt/adapter/flask/__init__.md → ...ference/slack_bolt/adapter/flask/index.md b/...ence/slack_bolt/adapter/flask/__init__.md → ...ference/slack_bolt/adapter/flask/index.md
diff --git a/...dapter/google_cloud_functions/__init__.md → ...t/adapter/google_cloud_functions/index.md b/...dapter/google_cloud_functions/__init__.md → ...t/adapter/google_cloud_functions/index.md
diff --git a/.../reference/slack_bolt/adapter/__init__.md → docs/reference/slack_bolt/adapter/index.md b/.../reference/slack_bolt/adapter/__init__.md → docs/reference/slack_bolt/adapter/index.md
diff --git a/...ce/slack_bolt/adapter/pyramid/__init__.md → ...rence/slack_bolt/adapter/pyramid/index.md b/...ce/slack_bolt/adapter/pyramid/__init__.md → ...rence/slack_bolt/adapter/pyramid/index.md
diff --git a/...ence/slack_bolt/adapter/sanic/__init__.md → ...ference/slack_bolt/adapter/sanic/index.md b/...ence/slack_bolt/adapter/sanic/__init__.md → ...ference/slack_bolt/adapter/sanic/index.md
diff --git a/...t/adapter/socket_mode/aiohttp/__init__.md → ...bolt/adapter/socket_mode/aiohttp/index.md b/...t/adapter/socket_mode/aiohttp/__init__.md → ...bolt/adapter/socket_mode/aiohttp/index.md
diff --git a/...t/adapter/socket_mode/builtin/__init__.md → ...bolt/adapter/socket_mode/builtin/index.md b/...t/adapter/socket_mode/builtin/__init__.md → ...bolt/adapter/socket_mode/builtin/index.md
diff --git a/...lack_bolt/adapter/socket_mode/__init__.md → ...e/slack_bolt/adapter/socket_mode/index.md b/...lack_bolt/adapter/socket_mode/__init__.md → ...e/slack_bolt/adapter/socket_mode/index.md
diff --git a/.../socket_mode/websocket_client/__init__.md → ...ter/socket_mode/websocket_client/index.md b/.../socket_mode/websocket_client/__init__.md → ...ter/socket_mode/websocket_client/index.md
diff --git a/...dapter/socket_mode/websockets/__init__.md → ...t/adapter/socket_mode/websockets/index.md b/...dapter/socket_mode/websockets/__init__.md → ...t/adapter/socket_mode/websockets/index.md
diff --git a/.../slack_bolt/adapter/starlette/__init__.md → ...nce/slack_bolt/adapter/starlette/index.md b/.../slack_bolt/adapter/starlette/__init__.md → ...nce/slack_bolt/adapter/starlette/index.md
diff --git a/...ce/slack_bolt/adapter/tornado/__init__.md → ...rence/slack_bolt/adapter/tornado/index.md b/...ce/slack_bolt/adapter/tornado/__init__.md → ...rence/slack_bolt/adapter/tornado/index.md
diff --git a/...rence/slack_bolt/adapter/wsgi/__init__.md → ...eference/slack_bolt/adapter/wsgi/index.md b/...rence/slack_bolt/adapter/wsgi/__init__.md → ...eference/slack_bolt/adapter/wsgi/index.md
diff --git a/docs/reference/slack_bolt/app/__init__.md → docs/reference/slack_bolt/app/index.md b/docs/reference/slack_bolt/app/__init__.md → docs/reference/slack_bolt/app/index.md
diff --git a/...ence/slack_bolt/authorization/__init__.md → ...ference/slack_bolt/authorization/index.md b/...ence/slack_bolt/authorization/__init__.md → ...ference/slack_bolt/authorization/index.md
diff --git a/...erence/slack_bolt/context/ack/__init__.md → ...reference/slack_bolt/context/ack/index.md b/...erence/slack_bolt/context/ack/__init__.md → ...reference/slack_bolt/context/ack/index.md
diff --git a/.../slack_bolt/context/assistant/__init__.md → ...nce/slack_bolt/context/assistant/index.md b/.../slack_bolt/context/assistant/__init__.md → ...nce/slack_bolt/context/assistant/index.md
diff --git a/...text/assistant/thread_context/__init__.md → ...context/assistant/thread_context/index.md b/...text/assistant/thread_context/__init__.md → ...context/assistant/thread_context/index.md
diff --git a/...ant/thread_context_store/file/__init__.md → ...istant/thread_context_store/file/index.md b/...ant/thread_context_store/file/__init__.md → ...istant/thread_context_store/file/index.md
diff --git a/...ssistant/thread_context_store/__init__.md → ...t/assistant/thread_context_store/index.md b/...ssistant/thread_context_store/__init__.md → ...t/assistant/thread_context_store/index.md
diff --git a/...e/slack_bolt/context/complete/__init__.md → ...ence/slack_bolt/context/complete/index.md b/...e/slack_bolt/context/complete/__init__.md → ...ence/slack_bolt/context/complete/index.md
diff --git a/...rence/slack_bolt/context/fail/__init__.md → ...eference/slack_bolt/context/fail/index.md b/...rence/slack_bolt/context/fail/__init__.md → ...eference/slack_bolt/context/fail/index.md
diff --git a/...lt/context/get_thread_context/__init__.md → ..._bolt/context/get_thread_context/index.md b/...lt/context/get_thread_context/__init__.md → ..._bolt/context/get_thread_context/index.md
diff --git a/.../reference/slack_bolt/context/__init__.md → docs/reference/slack_bolt/context/index.md b/.../reference/slack_bolt/context/__init__.md → docs/reference/slack_bolt/context/index.md
diff --git a/...ce/slack_bolt/context/respond/__init__.md → ...rence/slack_bolt/context/respond/index.md b/...ce/slack_bolt/context/respond/__init__.md → ...rence/slack_bolt/context/respond/index.md
diff --git a/...t/context/save_thread_context/__init__.md → ...bolt/context/save_thread_context/index.md b/...t/context/save_thread_context/__init__.md → ...bolt/context/save_thread_context/index.md
diff --git a/...erence/slack_bolt/context/say/__init__.md → ...reference/slack_bolt/context/say/index.md b/...erence/slack_bolt/context/say/__init__.md → ...reference/slack_bolt/context/say/index.md
diff --git a/...slack_bolt/context/say_stream/__init__.md → ...ce/slack_bolt/context/say_stream/index.md b/...slack_bolt/context/say_stream/__init__.md → ...ce/slack_bolt/context/say_stream/index.md
diff --git a/...slack_bolt/context/set_status/__init__.md → ...ce/slack_bolt/context/set_status/index.md b/...slack_bolt/context/set_status/__init__.md → ...ce/slack_bolt/context/set_status/index.md
diff --git a/...context/set_suggested_prompts/__init__.md → ...lt/context/set_suggested_prompts/index.md b/...context/set_suggested_prompts/__init__.md → ...lt/context/set_suggested_prompts/index.md
diff --git a/.../slack_bolt/context/set_title/__init__.md → ...nce/slack_bolt/context/set_title/index.md b/.../slack_bolt/context/set_title/__init__.md → ...nce/slack_bolt/context/set_title/index.md
diff --git a/docs/reference/slack_bolt/error/__init__.md → docs/reference/slack_bolt/error/index.md b/docs/reference/slack_bolt/error/__init__.md → docs/reference/slack_bolt/error/index.md
diff --git a/docs/reference/slack_bolt/__init__.md → docs/reference/slack_bolt/index.md b/docs/reference/slack_bolt/__init__.md → docs/reference/slack_bolt/index.md
diff --git a/...e/slack_bolt/kwargs_injection/__init__.md → ...ence/slack_bolt/kwargs_injection/index.md b/...e/slack_bolt/kwargs_injection/__init__.md → ...ence/slack_bolt/kwargs_injection/index.md
diff --git a/...ence/slack_bolt/lazy_listener/__init__.md → ...ference/slack_bolt/lazy_listener/index.md b/...ence/slack_bolt/lazy_listener/__init__.md → ...ference/slack_bolt/lazy_listener/index.md
diff --git a/...reference/slack_bolt/listener/__init__.md → docs/reference/slack_bolt/listener/index.md b/...reference/slack_bolt/listener/__init__.md → docs/reference/slack_bolt/listener/index.md
diff --git a/...e/slack_bolt/listener_matcher/__init__.md → ...ence/slack_bolt/listener_matcher/index.md b/...e/slack_bolt/listener_matcher/__init__.md → ...ence/slack_bolt/listener_matcher/index.md
diff --git a/docs/reference/slack_bolt/logger/__init__.md → docs/reference/slack_bolt/logger/index.md b/docs/reference/slack_bolt/logger/__init__.md → docs/reference/slack_bolt/logger/index.md
diff --git a/...ack_bolt/middleware/assistant/__init__.md → .../slack_bolt/middleware/assistant/index.md b/...ack_bolt/middleware/assistant/__init__.md → .../slack_bolt/middleware/assistant/index.md
diff --git a/...attaching_conversation_kwargs/__init__.md → ...re/attaching_conversation_kwargs/index.md b/...attaching_conversation_kwargs/__init__.md → ...re/attaching_conversation_kwargs/index.md
diff --git a/...ware/attaching_function_token/__init__.md → ...dleware/attaching_function_token/index.md b/...ware/attaching_function_token/__init__.md → ...dleware/attaching_function_token/index.md
diff --git a/...bolt/middleware/authorization/__init__.md → ...ck_bolt/middleware/authorization/index.md b/...bolt/middleware/authorization/__init__.md → ...ck_bolt/middleware/authorization/index.md
diff --git a/...ddleware/ignoring_self_events/__init__.md → .../middleware/ignoring_self_events/index.md b/...ddleware/ignoring_self_events/__init__.md → .../middleware/ignoring_self_events/index.md
diff --git a/...ference/slack_bolt/middleware/__init__.md → .../reference/slack_bolt/middleware/index.md b/...ference/slack_bolt/middleware/__init__.md → .../reference/slack_bolt/middleware/index.md
diff --git a/...ware/message_listener_matches/__init__.md → ...dleware/message_listener_matches/index.md b/...ware/message_listener_matches/__init__.md → ...dleware/message_listener_matches/index.md
diff --git a/...ddleware/request_verification/__init__.md → .../middleware/request_verification/index.md b/...ddleware/request_verification/__init__.md → .../middleware/request_verification/index.md
diff --git a/...ack_bolt/middleware/ssl_check/__init__.md → .../slack_bolt/middleware/ssl_check/index.md b/...ack_bolt/middleware/ssl_check/__init__.md → .../slack_bolt/middleware/ssl_check/index.md
diff --git a/...t/middleware/url_verification/__init__.md → ...bolt/middleware/url_verification/index.md b/...t/middleware/url_verification/__init__.md → ...bolt/middleware/url_verification/index.md
diff --git a/docs/reference/slack_bolt/oauth/__init__.md → docs/reference/slack_bolt/oauth/index.md b/docs/reference/slack_bolt/oauth/__init__.md → docs/reference/slack_bolt/oauth/index.md
diff --git a/.../reference/slack_bolt/request/__init__.md → docs/reference/slack_bolt/request/index.md b/.../reference/slack_bolt/request/__init__.md → docs/reference/slack_bolt/request/index.md
diff --git a/...reference/slack_bolt/response/__init__.md → docs/reference/slack_bolt/response/index.md b/...reference/slack_bolt/response/__init__.md → docs/reference/slack_bolt/response/index.md
diff --git a/docs/reference/slack_bolt/util/__init__.md → docs/reference/slack_bolt/util/index.md b/docs/reference/slack_bolt/util/__init__.md → docs/reference/slack_bolt/util/index.md
diff --git a/...eference/slack_bolt/workflows/__init__.md → docs/reference/slack_bolt/workflows/index.md b/...eference/slack_bolt/workflows/__init__.md → docs/reference/slack_bolt/workflows/index.md
diff --git a/...nce/slack_bolt/workflows/step/__init__.md → ...erence/slack_bolt/workflows/step/index.md b/...nce/slack_bolt/workflows/step/__init__.md → ...erence/slack_bolt/workflows/step/index.md
diff --git a/...bolt/workflows/step/utilities/__init__.md → ...ck_bolt/workflows/step/utilities/index.md b/...bolt/workflows/step/utilities/__init__.md → ...ck_bolt/workflows/step/utilities/index.md
@@ -16,6 +16,7 @@
 
 import copy
 import html
+import json
 import os
 import re
 
@@ -247,6 +248,47 @@ def main():
     inline_reexports(modules)
     session.process(modules)
     session.render(modules)
+    _rename_package_indexes()
+
+
+def _rename_package_indexes():
+    """Rename each package's ``__init__.md`` to ``index.md`` and rewrite the
+    generated ``sidebar.json`` to match.
+
+    The docusaurus renderer writes a package's docs to ``<pkg>/__init__.md``,
+    whose Docusaurus route is ``.../<pkg>/__init__`` -- there is no document at
+    the bare ``.../<pkg>/`` URL. Docusaurus serves ``index.md`` at the folder
+    URL, so renaming makes ``.../reference/slack_bolt/`` resolve (the path the
+    sidebar's Reference link points at) instead of 404ing.
+    """
+    reference_dir = os.path.join(REPO_ROOT, "docs", "reference")
+    renamed = 0
+    for dirpath, _dirnames, filenames in os.walk(reference_dir):
+        if "__init__.md" in filenames:
+            os.replace(
+                os.path.join(dirpath, "__init__.md"),
+                os.path.join(dirpath, "index.md"),
+            )
+            renamed += 1
+
+    sidebar_path = os.path.join(reference_dir, "sidebar.json")
+    with open(sidebar_path, encoding="utf-8") as handle:
+        sidebar = json.load(handle)
+
+    def rewrite(node):
+        if isinstance(node, str):
+            return node[: -len("__init__")] + "index" if node.endswith("/__init__") else node
+        if isinstance(node, list):
+            return [rewrite(item) for item in node]
+        if isinstance(node, dict):
+            return {key: rewrite(value) for key, value in node.items()}
+        return node
+
+    with open(sidebar_path, "w", encoding="utf-8") as handle:
+        json.dump(rewrite(sidebar), handle, indent=2)
+        handle.write("\n")
+
+    print("Renamed {} package __init__.md files to index.md".format(renamed))
 
 
 if __name__ == "__main__":