mirror of
https://github.com/apache/superset.git
synced 2026-05-28 19:25:20 +00:00
fix(docs): tighten onBrokenLinks to throw and fix surfaced broken links
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:
committed by
Evan Rusackas
parent
d1e9a5df06
commit
04451766e7
@@ -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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user