QT/superset2
1
0
Fork 0
mirror of https://github.com/apache/superset.git synced 2026-05-28 11:15:24 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
Previously docusaurus.config.ts had `onBrokenLinks: 'warn'`, so broken
internal links produced advisory warnings during build but didn't gate
merges. Tightening to `throw` surfaces every broken internal route at
build time. Three classes of issue fell out:

1. Stale `/docs/...` and `/docs/6.0.0/...` references in the 6.0.0
   versioned snapshot. The user-facing docs section was renamed
   `docs` → `user-docs` (routeBasePath) at some point after 6.0.0 was
   cut, but the snapshot's links still pointed at the old prefix. The
   live site redirects /docs/* → /user-docs/* at runtime, but
   Docusaurus's onBrokenLinks checker doesn't honor redirects.
   Bulk-rewrote /docs/* → /user-docs/* across the snapshot (and one
   /docs/api → /developer-docs/api).

2. Bare-relative MDX links like `[Label](./mcp)` (no .md/.mdx
   extension). Docusaurus renders an absolute href in SSR HTML, so
   static crawlers see correct links — BUT React Router's `<Link>`
   component on the client side resolves the bare path relative to
   the current URL on click, so when the page URL has a trailing
   slash (e.g. /extensions/overview/), `./mcp` becomes
   /extensions/overview/mcp (404). This is exactly the broken-flow a
   user reported on /developer-docs/extensions/overview/. Added the
   `.md`/`.mdx` extension to all 44 such links across 17 files; this
   makes Docusaurus resolve them to the canonical doc URL at the
   <Link> level, so SPA navigation works regardless of trailing slash.

3. Miscellaneous content fixes:
   - 4 `/configuration/feature-flags` references in 6.0.0 snapshot
     pointed at a page that doesn't exist in that version (the
     dedicated feature-flags page was added later). Repointed to the
     `#feature-flags` anchor inside `configuring-superset.mdx`.
   - 3 references to `superset-core/src/superset_core/rest_api/decorators.py`
     in extensions docs were rendered as relative URLs, resolving to
     /developer-docs/extensions/superset-core/... (404). Converted to
     absolute GitHub URLs.
   - 1 `/storybook/?path=...` link in extensions/components/index.mdx
     pointed at a non-existent route. Repointed to the existing
     `/developer-docs/testing/storybook` page that explains how to
     run Storybook locally.
   - 4 unclosed-paren markdown links in 6.0.0 installation-methods.mdx
     (pre-existing source bugs).

Build now passes with `onBrokenLinks: 'throw'`. Note that
`onBrokenAnchors` is still `'warn'` (default); a separate effort
should tighten that and fix the surviving anchor warnings (currently
~60 instances of `/community#superset-community-calendar`).
This commit is contained in:
Claude Code
2026-05-13 18:08:46 -07:00
committed by Evan Rusackas
parent d1e9a5df06
commit 04451766e7
37 changed files with 151 additions and 151 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docs/versioned_docs/version-6.0.0/installation/architecture.mdx
View File

@@ -24,10 +24,10 @@ A Superset installation is made up of these components:
The optional components above are necessary to enable these features:
- [Alerts and Reports](/docs/6.0.0/configuration/alerts-reports)
- [Caching](/docs/6.0.0/configuration/cache)
- [Async Queries](/docs/6.0.0/configuration/async-queries-celery/)
- [Dashboard Thumbnails](/docs/6.0.0/configuration/cache/#caching-thumbnails)
- [Alerts and Reports](/user-docs/6.0.0/configuration/alerts-reports)
- [Caching](/user-docs/6.0.0/configuration/cache)
- [Async Queries](/user-docs/6.0.0/configuration/async-queries-celery/)
- [Dashboard Thumbnails](/user-docs/6.0.0/configuration/cache/#caching-thumbnails)
If you install with Kubernetes or Docker Compose, all of these components will be created.
@@ -59,7 +59,7 @@ The caching layer serves two main functions:
- Store the results of queries to your data warehouse so that when a chart is loaded twice, it pulls from the cache the second time, speeding up the application and reducing load on your data warehouse.
- Act as a message broker for the worker, enabling the Alerts & Reports, async queries, and thumbnail caching features.
Most people use Redis for their cache, but Superset supports other options too. See the [cache docs](/docs/6.0.0/configuration/cache/) for more.
Most people use Redis for their cache, but Superset supports other options too. See the [cache docs](/user-docs/6.0.0/configuration/cache/) for more.
### Worker and Beat
@@ -67,6 +67,6 @@ This is one or more workers who execute tasks like run async queries or take sna
## Other components
Other components can be incorporated into Superset. The best place to learn about additional configurations is the [Configuration page](/docs/6.0.0/configuration/configuring-superset). For instance, you could set up a load balancer or reverse proxy to implement HTTPS in front of your Superset application, or specify a Mapbox URL to enable geospatial charts, etc.
Other components can be incorporated into Superset. The best place to learn about additional configurations is the [Configuration page](/user-docs/6.0.0/configuration/configuring-superset). For instance, you could set up a load balancer or reverse proxy to implement HTTPS in front of your Superset application, or specify a Mapbox URL to enable geospatial charts, etc.
Superset won't even start without certain configuration settings established, so it's essential to review that page.

2
docs/versioned_docs/version-6.0.0/installation/docker-compose.mdx
View File

@@ -21,7 +21,7 @@ with our [installing on k8s](https://superset.apache.org/docs/installation/runni
documentation.
:::
As mentioned in our [quickstart guide](/docs/quickstart), the fastest way to try
As mentioned in our [quickstart guide](/user-docs/quickstart), the fastest way to try
Superset locally is using Docker Compose on a Linux or Mac OSX
computer. Superset does not have official support for Windows. It's also the easiest
way to launch a fully functioning **development environment** quickly.

10
docs/versioned_docs/version-6.0.0/installation/installation-methods.mdx
View File

@@ -9,11 +9,11 @@ import useBaseUrl from "@docusaurus/useBaseUrl";
# Installation Methods
How should you install Superset? Here's a comparison of the different options. It will help if you've first read the [Architecture](/docs/6.0.0/installation/architecture page to understand Superset's different components.
How should you install Superset? Here's a comparison of the different options. It will help if you've first read the [Architecture](/user-docs/6.0.0/installation/architecture) page to understand Superset's different components.
The fundamental trade-off is between you needing to do more of the detail work yourself vs. using a more complex deployment route that handles those details.
## [Docker Compose](/docs/6.0.0/installation/docker-compose
## [Docker Compose](/user-docs/6.0.0/installation/docker-compose)
**Summary:** This takes advantage of containerization while remaining simpler than Kubernetes. This is the best way to try out Superset; it's also useful for developing & contributing back to Superset.
@@ -27,9 +27,9 @@ You will need to back up your metadata DB. That could mean backing up the servic
You will also need to extend the Superset docker image. The default `lean` images do not contain drivers needed to access your metadata database (Postgres or MySQL), nor to access your data warehouse, nor the headless browser needed for Alerts & Reports. You could run a `-dev` image while demoing Superset, which has some of this, but you'll still need to install the driver for your data warehouse. The `-dev` images run as root, which is not recommended for production.
Ideally you will build your own image of Superset that extends `lean`, adding what your deployment needs. See [Building your own production Docker image](/docs/6.0.0/installation/docker-builds/#building-your-own-production-docker-image).
Ideally you will build your own image of Superset that extends `lean`, adding what your deployment needs. See [Building your own production Docker image](/user-docs/6.0.0/installation/docker-builds/#building-your-own-production-docker-image).
## [Kubernetes (K8s)](/docs/6.0.0/installation/kubernetes
## [Kubernetes (K8s)](/user-docs/6.0.0/installation/kubernetes)
**Summary:** This is the best-practice way to deploy a production instance of Superset, but has the steepest skill requirement - someone who knows Kubernetes.
@@ -41,7 +41,7 @@ A K8s deployment can scale up and down based on usage and deploy rolling updates
You will need to build your own Docker image, and back up your metadata DB, both as described in Docker Compose above. You'll also need to customize your Helm chart values and deploy and maintain your Kubernetes cluster.
## [PyPI (Python)](/docs/6.0.0/installation/pypi
## [PyPI (Python)](/user-docs/6.0.0/installation/pypi)
**Summary:** This is the only method that requires no knowledge of containers. It requires the most hands-on work to deploy, connect, and maintain each component.

4
docs/versioned_docs/version-6.0.0/installation/kubernetes.mdx
View File

@@ -149,7 +149,7 @@ For production clusters it's recommended to build own image with this step done
Superset requires a Python DB-API database driver and a SQLAlchemy
dialect to be installed for each datastore you want to connect to.
See [Install Database Drivers](/docs/6.0.0/configuration/databases) for more information.
See [Install Database Drivers](/user-docs/6.0.0/configuration/databases) for more information.
It is recommended that you refer to versions listed in
[pyproject.toml](https://github.com/apache/superset/blob/master/pyproject.toml)
instead of hard-coding them in your bootstrap script, as seen below.
@@ -310,7 +310,7 @@ configOverrides:
### Enable Alerts and Reports
For this, as per the [Alerts and Reports doc](/docs/6.0.0/configuration/alerts-reports), you will need to:
For this, as per the [Alerts and Reports doc](/user-docs/6.0.0/configuration/alerts-reports), you will need to:
#### Install a supported webdriver in the Celery worker