merge doc changes

Author: msukkari

.github/workflows/docs-broken-links.yml

@@ -0,0 +1,26 @@
+name: Check for broken links in docs
+
+on:
+  pull_request:
+    branches: ["main"]
+    paths:
+      - "docs/**"
+
+jobs:
+  check-links:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Use Node.Js
+        uses: actions/setup-node@v4
+        with:
+            node-version: '20.x'
+
+      - name: Install Mintlify CLI
+        run: npm i -g mintlify
+
+      - name: Check for broken links
+        working-directory: docs
+        run: mintlify broken-links

CHANGELOG.md

@@ -22,14 +22,14 @@ Sourcebot V4 introduces authentication, performance improvements and code naviga
 ### Changed
 - [**Breaking Change**] Authentication is now required by default. Notes:
   - When setting up your instance, email / password login will be the default authentication provider.
-  - The first user that logs into the instance is given the `owner` role. ([docs](https://docs.sourcebot.dev/docs/more/roles-and-permissions)).
+  - The first user that logs into the instance is given the `owner` role. ([docs](https://docs.sourcebot.dev/docs/configuration/auth/roles-and-permissions)).
   - Subsequent users can request to join the instance. The `owner` can approve / deny requests to join the instance via `Settings` > `Members` > `Pending Requests`.
   - If a user is approved to join the instance, they are given the `member` role.
-  - Additional login providers, including email links and SSO, can be configured with additional environment variables. ([docs](https://docs.sourcebot.dev/docs/configuration/authentication)).
+  - Additional login providers, including email links and SSO, can be configured with additional environment variables. ([docs](https://docs.sourcebot.dev/docs/configuration/auth/overview)).
 - Clicking on a search result now takes you to the `/browse` view. Files can still be previewed by clicking the "Preview" button or holding `Cmd` / `Ctrl` when clicking on a search result. [#315](https://github.com/sourcebot-dev/sourcebot/pull/315)
 
 ### Added
-- [Sourcebot EE] Added search-based code navigation, allowing you to jump between symbol definition and references when viewing source files. [Read the documentation](https://docs.sourcebot.dev/docs/search/code-navigation). [#315](https://github.com/sourcebot-dev/sourcebot/pull/315)
+- [Sourcebot EE] Added search-based code navigation, allowing you to jump between symbol definition and references when viewing source files. [Read the documentation](https://docs.sourcebot.dev/docs/features/code-navigation). [#315](https://github.com/sourcebot-dev/sourcebot/pull/315)
 - Added collapsible filter panel. [#315](https://github.com/sourcebot-dev/sourcebot/pull/315)
 - Added Sourcebot API key management for external clients. [#311](https://github.com/sourcebot-dev/sourcebot/pull/311)
 
@@ -44,7 +44,7 @@ Sourcebot V4 introduces authentication, performance improvements and code naviga
 ## [3.2.0] - 2025-05-12
 
 ### Added
-- Added AI code review agent [#298](https://github.com/sourcebot-dev/sourcebot/pull/298). Checkout the [docs](https://docs.sourcebot.dev/docs/agents/review-agent) for more information.
+- Added AI code review agent [#298](https://github.com/sourcebot-dev/sourcebot/pull/298). Checkout the [docs](https://docs.sourcebot.dev/docs/features/agents/review-agent) for more information.
 
 ### Fixed
 - Fixed issue with repos appearing in the carousel when they fail indexing for the first time. [#305](https://github.com/sourcebot-dev/sourcebot/pull/305)
@@ -122,11 +122,11 @@ Sourcebot v3 is here and brings a number of structural changes to the tool's fou
 ### Added
 - Added parallelized repo indexing and connection syncing via Redis & BullMQ. See the [architecture overview](https://docs.sourcebot.dev/docs/overview#architecture).
 - Added repo indexing progress indicators in the navbar.
-- Added authentication support via OAuth or email/password. For instructions on enabling, see [this doc](https://docs.sourcebot.dev/docs/configuration/authentication).
-- Added the following UI for managing your deployment when **[auth is enabled](https://docs.sourcebot.dev/docs/configuration/authentication)**:
+- Added authentication support via OAuth or email/password. For instructions on enabling, see [this doc](https://docs.sourcebot.dev/docs/configuration/auth/overview).
+- Added the following UI for managing your deployment when **[auth is enabled](https://docs.sourcebot.dev/docs/configuration/auth/overview)**:
   - connection management: create and manage your JSON configs via a integrated web-editor.
   - secrets: import personal access tokens (PAT) into Sourcebot (AES-256 encrypted). Reference secrets in your connection config by name.
-  - team & invite management: invite users to your instance to give them access. Configure team [roles & permissions](https://docs.sourcebot.dev/docs/more/roles-and-permissions).
+  - team & invite management: invite users to your instance to give them access. Configure team [roles & permissions](https://docs.sourcebot.dev/docs/configuration/auth/roles-and-permissions).
 - Added multi-tenancy support. See [this doc](https://docs.sourcebot.dev/self-hosting/more/tenancy).
 
 ### Removed

docs/development.mdx

@@ -21,8 +21,30 @@
                         "group": "Getting Started",
                         "pages": [
                             "docs/overview",
-                            "docs/quick-start-guide",
-                            "docs/license-key"
+                            "docs/deployment-guide"
+                        ]
+                    },
+                    {
+                        "group": "Features",
+                        "pages": [
+                            {
+                                "group": "Search",
+                                "pages": [
+                                    "docs/features/search/syntax-reference",
+                                    "docs/features/search/multi-branch-indexing",
+                                    "docs/features/search/search-contexts"
+                                ]
+                            },
+                            "docs/features/code-navigation",
+                            "docs/features/mcp-server",
+                            {
+                                "group": "Agents",
+                                "tag": "experimental",
+                                "pages": [
+                                    "docs/features/agents/overview",
+                                    "docs/features/agents/review-agent"
+                                ]
+                            }
                         ]
                     },
                     {
@@ -43,34 +65,17 @@
                                     "docs/connections/request-new"
                                 ]
                             },
+                            "docs/license-key",
                             "docs/configuration/environment-variables",
-                            "docs/configuration/authentication",
-                            "docs/configuration/transactional-emails"
-                        ]
-                    },
-                    {
-                        "group": "Search",
-                        "pages": [
-                            "docs/search/syntax-reference",
-                            "docs/search/multi-branch-indexing",
-                            "docs/search/code-navigation",
-                            "docs/search/search-contexts"
-                        ]
-                    },
-                    {
-                        "group": "Agents",
-                        "pages": [
-                            "docs/agents/overview",
-                            "docs/agents/review-agent"
-                        ]
-                    },
-                    {
-                        "group": "More",
-                        "pages": [
-                            "docs/more/api-keys",
-                            "docs/more/roles-and-permissions",
-                            "docs/more/mcp-server",
-                            "docs/more/structured-logging"
+                            {
+                                "group": "Authentication",
+                                "pages": [
+                                    "docs/configuration/auth/overview",
+                                    "docs/configuration/auth/roles-and-permissions"
+                                ]
+                            },
+                            "docs/configuration/transactional-emails",
+                            "docs/configuration/structured-logging"
                         ]
                     },
                     {

docs/docs.json

@@ -1,13 +1,10 @@
 ---
-title: Authentication
-sidebarTitle: Authentication
+title: Overview
 ---
 
-<Warning>Make sure the `AUTH_URL` environment variable is [configured correctly](/self-hosting/configuration) when using Sourcebot behind a domain.</Warning>
-
 Sourcebot has built-in authentication that gates access to your organization. OAuth, email codes, and email / password are supported. 
 
-The first account that's registered on a Sourcebot deployment is made the owner. All other users who register must be [approved](/docs/configuration/authentication#approving-new-members) by the owner.
+The first account that's registered on a Sourcebot deployment is made the owner. All other users who register must be [approved](/docs/configuration/auth/overview#approving-new-members) by the owner.
 
 ![Login Page](/images/login.png)
 
@@ -16,7 +13,7 @@ The first account that's registered on a Sourcebot deployment is made the owner.
 
 All account registrations after the first account must be approved by the owner. The owner can see all join requests by going into **Settings -> Members**.
 
-If you have an [enterprise license](/docs/license-key), you can enable [AUTH_EE_ENABLE_JIT_PROVISIONING](/docs/configuration/authentication#enterprise-authentication-providers) to 
+If you have an [enterprise license](/docs/license-key), you can enable [AUTH_EE_ENABLE_JIT_PROVISIONING](/docs/configuration/auth/overview#enterprise-authentication-providers) to 
 have Sourcebot accounts automatically created and approved on registration.
 
 You can setup emails to be sent when new join requests are created/approved by configurating [transactional emails](/docs/configuration/transactional-emails)
@@ -43,6 +40,8 @@ See [transactional emails](/docs/configuration/transactional-emails) for more de
 
 ## Enterprise Authentication Providers
 
+<Warning>If you're deploying Sourcebot behind a domain, you must set the [AUTH_URL](/docs/configuration/environment-variables) environment variable to use these providers.</Warning>
+
 The following authentication providers require an [enterprise license](/docs/license-key) to be enabled.
 
 By default, a new user registering using these providers must have their join request accepted by the owner of the organization to join. To allow a user to join automatically when

docs/docs/configuration/authentication.mdx renamed to docs/docs/configuration/auth/overview.mdx

@@ -1,17 +1,18 @@
 ---
-title: Environment Variables 
-sidebarTitle: Environment Variables 
+title: Environment variables 
+sidebarTitle: Environment variables 
+mode: "wide"
 ---
 
-<Note>This page provides a detailed reference of all environment variables supported by Sourcebot. If you're just looking to get up and running, we recommend starting with the [getting started](/self-hosting/overview) guide instead.</Note>
+<Note>This page provides a detailed reference of all environment variables supported by Sourcebot. If you're just looking to get up and running, we recommend starting with the [deployment guide](/docs/deployment-guide) instead.</Note>
 
 ### Core Environment Variables
 The following environment variables allow you to configure your Sourcebot deployment.
 
 | Variable | Default | Description |
 | :------- | :------ | :---------- |
-| `AUTH_CREDENTIALS_LOGIN_ENABLED` | `true` | <p>Enables/disables authentication with basic credentials. Username and passwords are stored encrypted at rest within the postgres database. Checkout the [auth docs](/docs/configuration/authentication) for more info</p> |
-| `AUTH_EMAIL_CODE_LOGIN_ENABLED` | `false` | <p>Enables/disables authentication with a login code that's sent to a users email. `SMTP_CONNECTION_URL` and `EMAIL_FROM_ADDRESS` must also be set. Checkout the [auth docs](/docs/configuration/authentication) for more info </p> |
+| `AUTH_CREDENTIALS_LOGIN_ENABLED` | `true` | <p>Enables/disables authentication with basic credentials. Username and passwords are stored encrypted at rest within the postgres database. Checkout the [auth docs](/docs/configuration/auth/overview) for more info</p> |
+| `AUTH_EMAIL_CODE_LOGIN_ENABLED` | `false` | <p>Enables/disables authentication with a login code that's sent to a users email. `SMTP_CONNECTION_URL` and `EMAIL_FROM_ADDRESS` must also be set. Checkout the [auth docs](/docs/configuration/auth/overview) for more info </p> |
 | `AUTH_SECRET` | Automatically generated at startup if no value is provided. Generated using `openssl rand -base64 33` | <p>Used to validate login session cookies</p> |
 | `AUTH_URL` | - | <p>URL of your Sourcebot deployment, e.g., `https://example.com` or `http://localhost:3000`.</p> |
 | `CONFIG_PATH` | `-` | <p>The container relative path to the declerative configuration file. See [this doc](/docs/configuration/declarative-config) for more info.</p> | 
@@ -28,7 +29,7 @@ The following environment variables allow you to configure your Sourcebot deploy
 | `SOURCEBOT_LOG_LEVEL` | `info` | <p>The Sourcebot logging level. Valid values are `debug`, `info`, `warn`, `error`, in order of severity.</p> |
 | `SOURCEBOT_STRUCTURED_LOGGING_ENABLED` | `false` | <p>Enables/disable structured JSON logging. See [this doc](/docs/configuration/transactional-emails) for more info.</p> |
 | `SOURCEBOT_STRUCTURED_LOGGING_FILE` | - | <p>Optional file to log to if structured logging is enabled</p> | 
-| `SOURCEBOT_TELEMETRY_DISABLED` | `false` | <p>Enables/disables telemetry collection in Sourcebot. See [this doc](/docs/more/structured-logging) for more info.</p> |
+| `SOURCEBOT_TELEMETRY_DISABLED` | `false` | <p>Enables/disables telemetry collection in Sourcebot. See [this doc](/docs/overview.mdx#telemetry) for more info.</p> |
 | `TOTAL_MAX_MATCH_COUNT` | `100000` | <p>The maximum number of matches per query</p> |
 | `ZOEKT_MAX_WALL_TIME_MS` | `10000` | <p>The maximum real world duration (in milliseconds) per zoekt query</p> | 
 

docs/docs/more/roles-and-permissions.mdx renamed to docs/docs/configuration/auth/roles-and-permissions.mdx

@@ -4,7 +4,7 @@ sidebarTitle: Multi tenancy
 ---
 
 <Warning>If you're switching from single-tenant mode, delete the Sourcebot cache (the `.sourcebot` folder) before starting.</Warning>
-<Warning>[Authentication](/docs/configuration/authentication) must be enabled to enable multi tenancy mode</Warning>
+<Warning>[Authentication](/docs/configuration/auth/overview) must be enabled to enable multi tenancy mode</Warning>
 Multi tenancy allows your Sourcebot deployment to have **multiple organizations**, each with their own set of members and repos. To enable multi tenancy mode, define an environment variable
 named `SOURCEBOT_TENANCY_MODE` and set its value to `multi`. When multi tenancy mode is enabled:
 

docs/docs/configuration/environment-variables.mdx

@@ -7,7 +7,7 @@ To enable transactional emails in your deployment, set the following environment
 
 - Send emails when new members are invited
 - Send emails when organization join requests are created/accepted
-- Log into the Sourcebot deployment using [email codes](self-hosting/more/authentication#email-codes)
+- Log into the Sourcebot deployment using [email codes](/docs/configuration/auth/overview#email-codes)
 
 | Variable | Description |
 | :------- | :---------- |