wip on docs

Author: brendan-kellam

docs/docs.json

@@ -29,19 +29,25 @@
                         "group": "Connecting your code",
                         "pages": [
                             "docs/connections/overview",
-                            "docs/connections/github",
-                            "docs/connections/gitlab",
-                            "docs/connections/bitbucket-cloud",
-                            "docs/connections/bitbucket-data-center",
-                            "docs/connections/gitea",
-                            "docs/connections/gerrit",
-                            "docs/connections/request-new"
+                            {
+                                "group": "Supported platforms",
+                                "pages": [
+                                    "docs/connections/github",
+                                    "docs/connections/gitlab",
+                                    "docs/connections/bitbucket-cloud",
+                                    "docs/connections/bitbucket-data-center",
+                                    "docs/connections/gitea",
+                                    "docs/connections/gerrit",
+                                    "docs/connections/request-new"
+                                ]
+                            }
                         ]
                     },
                     {
                         "group": "More",
                         "pages": [
                             "docs/more/syntax-reference",
+                            "docs/more/multi-branch-indexing",
                             "docs/more/roles-and-permissions"
                         ]
                     }

docs/docs/more/multi-branch-indexing.mdx

@@ -0,0 +1,75 @@
+---
+title: Searching multiple branches and tags
+sidebarTitle: Searching multiple branches
+---
+
+By default, only the default branch of a repository is indexed and can be searched. Sourcebot can be configured to index additional branches (or tags) enabling multi-branch search. This is useful for scenarios such as:
+
+- Searching across different releases
+- Searching through feature branches during development
+- Tracking changes across multiple maintenance branches simultaneously
+
+## Configuration
+
+<Warning>
+Multi-branch indexing is currently limited to 64 branches and tags. If this limitation impacts your use-case, please [open a discussion](https://github.com/sourcebot-dev/sourcebot/discussions/categories/support).
+</Warning>
+
+Multi-branch indexing is configured on in the [connection](/docs/connections/overview) using the `revisions.branches` and `revisions.tags` arrays. Glob patterns are supported. For example:
+
+```json
+{
+    "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json",
+    "connections": {
+        "my-connection": {
+            "type": "github",
+            // For each of the repositories defined in this connection...
+            "repos": [
+                "org/repo1",
+                "org/repo2"
+            ],
+            // ... index the default branch, as well as...
+            "revisions": {
+                // These branches (if they exist):
+                "branches": [
+                    // Exact matches
+                    "dev",
+                    "staging",
+
+                    // Glob patterns
+                    "feature/*" // Matches: feature/auth, feature/ui, etc.
+                ],
+                
+                // These tags (if they exist):
+                "tags": [
+                    // Exact matches
+                    "v4.0.0-dev",
+                    
+                    // Glob patterns
+                    "v3.*.*", // Matches: v3.0.0, v3.0.1, etc.
+                    "rc-*"    // Matches: rc-1, rc-2, etc.
+                ]
+            }
+        }
+    }
+}
+```
+
+For each repo defined in the connection, any branches or tags matching the patterns in `branches` and `tags` array will be indexed.
+
+## Search syntax
+
+todo
+
+
+## Platform support
+
+| Platform | Multi-branch indexing support |
+|:----------|------------------------------|
+| GitHub | ✅ |
+| GitLab | ✅ |
+| Bitbucket Cloud | ✅ |
+| Bitbucket Data Center | ✅ |
+| Gitea | ✅ |
+| Gerrit | ❌ |
+