fix(docs): tighten onBrokenLinks to throw and fix surfaced broken links (#40102)

Co-authored-by: Claude Code <noreply@anthropic.com>

docs/developer_docs/extensions/architecture.md

@@ -233,7 +233,7 @@ This architecture provides several key benefits:
 
 Now that you understand the architecture, explore:
 
-- **[Dependencies](./dependencies)** - Managing dependencies and understanding API stability
-- **[Quick Start](./quick-start)** - Build your first extension
-- **[Contribution Types](./contribution-types)** - What kinds of extensions you can build
-- **[Development](./development)** - Project structure, APIs, and development workflow
+- **[Dependencies](./dependencies.md)** - Managing dependencies and understanding API stability
+- **[Quick Start](./quick-start.md)** - Build your first extension
+- **[Contribution Types](./contribution-types.md)** - What kinds of extensions you can build
+- **[Development](./development.md)** - Project structure, APIs, and development workflow

docs/developer_docs/extensions/components/index.mdx

@@ -29,7 +29,7 @@ These UI components are available to Superset extension developers through the `
 
 ## Available Components
 
-- [Alert](./alert)
+- [Alert](./alert.mdx)
 
 ## Usage
 
@@ -90,4 +90,4 @@ InteractiveMyComponent.argTypes = {
 
 ## Interactive Documentation
 
-For interactive examples with controls, visit the [Storybook](/storybook/?path=/docs/extension-components--docs).
+For interactive examples with controls, run Storybook locally — see the [Storybook documentation](/developer-docs/testing/storybook).

docs/developer_docs/extensions/contribution-types.md

@@ -110,7 +110,7 @@ editors.registerEditor(
 );
 ```
 
-See [Editors Extension Point](./extension-points/editors) for implementation details.
+See [Editors Extension Point](./extension-points/editors.md) for implementation details.
 
 ## Backend
 
@@ -146,7 +146,7 @@ class MyExtensionAPI(RestApi):
 from .api import MyExtensionAPI
 ```
 
-**Note**: The [`@api`](superset-core/src/superset_core/rest_api/decorators.py) decorator automatically detects context and generates appropriate paths:
+**Note**: The [`@api`](https://github.com/apache/superset/blob/master/superset-core/src/superset_core/rest_api/decorators.py) decorator automatically detects context and generates appropriate paths:
 
 - **Extension context**: `/extensions/{publisher}/{name}/` with ID prefixed as `extensions.{publisher}.{name}.{id}`
 - **Host context**: `/api/v1/` with original ID
@@ -193,7 +193,7 @@ def get_summary() -> dict:
     return {"status": "success", "result": {"queries_today": 42}}
 ```
 
-See [MCP Integration](./mcp) for implementation details.
+See [MCP Integration](./mcp.md) for implementation details.
 
 ### MCP Prompts
 
@@ -223,7 +223,7 @@ async def analysis_guide(ctx: Context) -> str:
     """
 ```
 
-See [MCP Integration](./mcp) for implementation details.
+See [MCP Integration](./mcp.md) for implementation details.
 
 ### Semantic Layers
 

docs/developer_docs/extensions/dependencies.md

@@ -161,6 +161,6 @@ Until then, monitor the Superset release notes and test your extensions with eac
 
 ## Next Steps
 
-- **[Architecture](./architecture)** - Understand the extension system design
-- **[Development](./development)** - Learn about APIs and development workflow
-- **[Quick Start](./quick-start)** - Build your first extension
+- **[Architecture](./architecture.md)** - Understand the extension system design
+- **[Development](./development.md)** - Learn about APIs and development workflow
+- **[Quick Start](./quick-start.md)** - Build your first extension

docs/developer_docs/extensions/development.md

@@ -252,7 +252,7 @@ class DatasetReferencesAPI(RestApi):
 
 ### Automatic Context Detection
 
-The [`@api`](superset-core/src/superset_core/rest_api/decorators.py) decorator automatically detects whether it's being used in host or extension code:
+The [`@api`](https://github.com/apache/superset/blob/master/superset-core/src/superset_core/rest_api/decorators.py) decorator automatically detects whether it's being used in host or extension code:
 
 - **Extension APIs**: Registered under `/extensions/{publisher}/{name}/` with IDs prefixed as `extensions.{publisher}.{name}.{id}`
 - **Host APIs**: Registered under `/api/v1/` with original IDs

docs/developer_docs/extensions/extension-points/editors.md

@@ -217,6 +217,6 @@ const disposable = handle.registerCompletionProvider(provider);
 
 ## Next Steps
 
-- **[SQL Lab Extension Points](./sqllab)** - Learn about other SQL Lab customizations
-- **[Contribution Types](../contribution-types)** - Explore other contribution types
-- **[Development](../development)** - Set up your development environment
+- **[SQL Lab Extension Points](./sqllab.md)** - Learn about other SQL Lab customizations
+- **[Contribution Types](../contribution-types.md)** - Explore other contribution types
+- **[Development](../development.md)** - Set up your development environment

docs/developer_docs/extensions/extension-points/sqllab.md

@@ -51,7 +51,7 @@ SQL Lab provides 4 extension points where extensions can contribute custom UI co
 | **Right Sidebar** | `sqllab.rightSidebar` | ✓     | —     | Custom panels (AI assistants, query analysis)  |
 | **Panels**        | `sqllab.panels`       | ✓     | ✓     | Custom tabs + toolbar actions (data profiling) |
 
-\*Editor views are contributed via [Editor Contributions](./editors), not standard view contributions.
+\*Editor views are contributed via [Editor Contributions](./editors.md), not standard view contributions.
 
 ## Customization Types
 
@@ -78,7 +78,7 @@ Extensions can add toolbar actions to **Left Sidebar**, **Editor**, and **Panels
 
 ### Custom Editors
 
-Extensions can replace the default SQL editor with custom implementations (Monaco, CodeMirror, etc.). See [Editor Contributions](./editors) for details.
+Extensions can replace the default SQL editor with custom implementations (Monaco, CodeMirror, etc.). See [Editor Contributions](./editors.md) for details.
 
 ## Examples
 
@@ -157,6 +157,6 @@ menus.registerMenuItem(
 
 ## Next Steps
 
-- **[Contribution Types](../contribution-types)** - Learn about other contribution types (commands, menus)
-- **[Development](../development)** - Set up your development environment
-- **[Quick Start](../quick-start)** - Build a complete extension
+- **[Contribution Types](../contribution-types.md)** - Learn about other contribution types (commands, menus)
+- **[Development](../development.md)** - Set up your development environment
+- **[Quick Start](../quick-start.md)** - Build a complete extension

docs/developer_docs/extensions/mcp.md

@@ -455,5 +455,5 @@ async def metrics_guide(ctx: Context) -> str:
 
 ## Next Steps
 
-- **[Development](./development)** - Project structure, APIs, and dev workflow
-- **[Security](./security)** - Security best practices for extensions
+- **[Development](./development.md)** - Project structure, APIs, and dev workflow
+- **[Security](./security.md)** - Security best practices for extensions

docs/developer_docs/extensions/overview.md

@@ -47,13 +47,13 @@ Extension developers have access to pre-built UI components via `@apache-superse
 
 ## Next Steps
 
-- **[Quick Start](./quick-start)** - Build your first extension with a complete walkthrough
-- **[Architecture](./architecture)** - Design principles and system overview
-- **[Dependencies](./dependencies)** - Managing dependencies and understanding API stability
-- **[Contribution Types](./contribution-types)** - Available extension points
-- **[Development](./development)** - Project structure, APIs, and development workflow
-- **[Deployment](./deployment)** - Packaging and deploying extensions
-- **[MCP Integration](./mcp)** - Adding AI agent capabilities using extensions
-- **[Security](./security)** - Security considerations and best practices
-- **[Tasks](./tasks)** - Framework for creating and managing long running tasks
-- **[Community Extensions](./registry)** - Browse extensions shared by the community
+- **[Quick Start](./quick-start.md)** - Build your first extension with a complete walkthrough
+- **[Architecture](./architecture.md)** - Design principles and system overview
+- **[Dependencies](./dependencies.md)** - Managing dependencies and understanding API stability
+- **[Contribution Types](./contribution-types.md)** - Available extension points
+- **[Development](./development.md)** - Project structure, APIs, and development workflow
+- **[Deployment](./deployment.md)** - Packaging and deploying extensions
+- **[MCP Integration](./mcp.md)** - Adding AI agent capabilities using extensions
+- **[Security](./security.md)** - Security considerations and best practices
+- **[Tasks](./tasks.md)** - Framework for creating and managing long running tasks
+- **[Community Extensions](./registry.md)** - Browse extensions shared by the community

docs/developer_docs/extensions/quick-start.md

@@ -168,7 +168,7 @@ class HelloWorldAPI(RestApi):
 
 **Key points:**
 
-- Uses [`@api`](superset-core/src/superset_core/rest_api/decorators.py) decorator with automatic context detection
+- Uses [`@api`](https://github.com/apache/superset/blob/master/superset-core/src/superset_core/rest_api/decorators.py) decorator with automatic context detection
 - Extends `RestApi` from `superset_core.rest_api.api`
 - Uses Flask-AppBuilder decorators (`@expose`, `@protect`, `@safe`)
 - Returns responses using `self.response(status_code, result=data)`
@@ -184,7 +184,7 @@ Replace the generated print statement with API import to trigger registration:
 from .api import HelloWorldAPI  # noqa: F401
 ```
 
-The [`@api`](superset-core/src/superset_core/rest_api/decorators.py) decorator automatically detects extension context and registers your API with proper namespacing.
+The [`@api`](https://github.com/apache/superset/blob/master/superset-core/src/superset_core/rest_api/decorators.py) decorator automatically detects extension context and registers your API with proper namespacing.
 
 ## Step 5: Create Frontend Component
 
@@ -225,7 +225,7 @@ The `@apache-superset/core` package must be listed in both `peerDependencies` (t
 
 The webpack configuration requires specific settings for Module Federation. Key settings include `externalsType: "window"` and `externals` to map `@apache-superset/core` to `window.superset` at runtime, `import: false` for shared modules to use the host's React instead of bundling a separate copy, and `remoteEntry.[contenthash].js` for cache busting.
 
-**Convention**: Superset always loads extensions by requesting the `./index` module from the Module Federation container. The `exposes` entry must be exactly `'./index': './src/index.tsx'` — do not rename or add additional entries. All API registrations must be reachable from that file. See [Architecture](./architecture#module-federation) for a full explanation.
+**Convention**: Superset always loads extensions by requesting the `./index` module from the Module Federation container. The `exposes` entry must be exactly `'./index': './src/index.tsx'` — do not rename or add additional entries. All API registrations must be reachable from that file. See [Architecture](./architecture.md#module-federation) for a full explanation.
 
 ```javascript
 const path = require('path');
@@ -496,7 +496,7 @@ Superset will extract and validate the extension metadata, load the assets, regi
 Here's what happens when your extension loads:
 
 1. **Superset starts**: Reads `manifest.json` from the `.supx` bundle and loads the backend entrypoint
-2. **Backend registration**: `entrypoint.py` imports your API class, triggering the [`@api`](superset-core/src/superset_core/rest_api/decorators.py) decorator to register it automatically
+2. **Backend registration**: `entrypoint.py` imports your API class, triggering the [`@api`](https://github.com/apache/superset/blob/master/superset-core/src/superset_core/rest_api/decorators.py) decorator to register it automatically
 3. **Frontend loads**: When SQL Lab opens, Superset fetches the remote entry file
 4. **Module Federation**: Webpack loads your extension module and resolves `@apache-superset/core` to `window.superset`
 5. **Registration**: The module executes at load time, calling `views.registerView` to register your panel
@@ -509,9 +509,9 @@ Here's what happens when your extension loads:
 
 Now that you have a working extension, explore:
 
-- **[Development](./development)** - Project structure, APIs, and development workflow
-- **[Contribution Types](./contribution-types)** - Other contribution points beyond panels
-- **[Deployment](./deployment)** - Packaging and deploying your extension
-- **[Security](./security)** - Security best practices for extensions
+- **[Development](./development.md)** - Project structure, APIs, and development workflow
+- **[Contribution Types](./contribution-types.md)** - Other contribution points beyond panels
+- **[Deployment](./deployment.md)** - Packaging and deploying your extension
+- **[Security](./security.md)** - Security best practices for extensions
 
 For a complete real-world example, examine the query insights extension in the Superset codebase.

docs/developer_docs/extensions/security.md

@@ -28,7 +28,7 @@ By default, extensions are disabled and must be explicitly enabled by setting th
 
 For external extensions, administrators are responsible for evaluating and verifying the security of any extensions they choose to install, just as they would when installing third-party NPM or PyPI packages. At this stage, all extensions run in the same context as the host application, without additional sandboxing. This means that external extensions can impact the security and performance of a Superset environment in the same way as any other installed dependency.
 
-We plan to introduce an optional sandboxed execution model for extensions in the future (as part of an additional SIP). Until then, administrators should exercise caution and follow best practices when selecting and deploying third-party extensions. A directory of community extensions is available in the [Community Extensions](./registry) page. Note that these extensions are not vetted by the Apache Superset project—administrators must evaluate each extension before installation.
+We plan to introduce an optional sandboxed execution model for extensions in the future (as part of an additional SIP). Until then, administrators should exercise caution and follow best practices when selecting and deploying third-party extensions. A directory of community extensions is available in the [Community Extensions](./registry.md) page. Note that these extensions are not vetted by the Apache Superset project—administrators must evaluate each extension before installation.
 
 **Any performance or security vulnerabilities introduced by external extensions should be reported directly to the extension author, not as Superset vulnerabilities.**