Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: set up redirects #28247

Merged
merged 4 commits into from
Apr 29, 2024
Merged

docs: set up redirects #28247

merged 4 commits into from
Apr 29, 2024

Conversation

mistercrunch
Copy link
Member

@mistercrunch mistercrunch commented Apr 28, 2024

SUMMARY

Someone filled an issue about search index referring to dead links in our
documentation. Turns out many of the top links when googling apache superset documentation point to 404s now.

In this PR I'm trying to set up client-side redirects to the related pages.

Note that the docs for this plugin state that server-side redirects are
better, and that the redirects don't work in dev, only prod, which
makes it hard to test

In the future, we'll need more rigor around catching dead links,
either during code review for the docs, or through some docusaurus
automation magic forcing us to come up with redirects whenever we kill
routes.

Docusaurus redirect plugin documentation for reference

Testing

I took the freedom to run gh workflow run superset-docs-deploy.yml -r docs_redirect, logs here since there's no way to test in dev and wanted this fix asap.

closes #28245

Someone filled an issue about search index referring to dead links in our
documentation. Turns out many of the top links when googling `apache
superset documentation` point to 404s now.

In this PR I'm trying to set up client-side redirects to the related pages.

Note that the docs for this plugin state that server-side redirects are
better, and that the redirects don't work in dev, only prod, which
makes it hard to test

In the future, we'll need more rigor around catching dead links,
either during code review for the docs, or through some docusaurus
automation magic forcing us to come up with redirects whenever we kill
routes.
@github-actions github-actions bot added doc Namespace | Anything related to documentation preset-io labels Apr 28, 2024
@mistercrunch
Copy link
Member Author

Ok looks like this work, there may be more dead links indexed, but should cover the first few pages of google results when googling apache superset documentation

@mistercrunch
Copy link
Member Author

Unclear how much better are server-side redirects for this purpose, but search engines may do better with a clear permanent redirect (http 301)

Copy link
Member

@sfirke sfirke left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Important fix to the docs, thank you. I went through this recent PR #28161 and added additional redirects where:

  • The result was broken coming from a search engine, and
  • It wasn't yet fixed in the file on your branch

docs/docusaurus.config.js Outdated Show resolved Hide resolved
docs/docusaurus.config.js Show resolved Hide resolved
@pull-request-size pull-request-size bot added size/M and removed size/S labels Apr 29, 2024
@mistercrunch
Copy link
Member Author

In terms of preventing dead link while allowing us to do more of these much needed refactors, I see two options:

  • rigor and caution in docs PR reviews, make sure all orphaned routes are rewired some place
  • set up some automation that prevents dead link. While working with the redirect plugin, I noticed it'll check and complain when there's a redirect to a link that's unknown to docusaurus. That means we could we could set up dummy redirect to every single existing route that would fail the build when becoming orphaned

@sfirke
Copy link
Member

sfirke commented Apr 29, 2024

Failing the build upon a broken link seems reasonable to me and more likely to succeed than diligent reviews.

@mistercrunch mistercrunch merged commit f9f0bc6 into master Apr 29, 2024
28 checks passed
@mistercrunch mistercrunch deleted the docs_redirect branch April 29, 2024 17:38
jzhao62 pushed a commit to jzhao62/superset that referenced this pull request May 16, 2024
vinothkumar66 pushed a commit to vinothkumar66/superset that referenced this pull request Nov 11, 2024
@mistercrunch mistercrunch added 🏷️ bot A label used by `supersetbot` to keep track of which PR where auto-tagged with release labels 🚢 4.1.0 labels Nov 27, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
🏷️ bot A label used by `supersetbot` to keep track of which PR where auto-tagged with release labels doc Namespace | Anything related to documentation preset-io size/M 🚢 4.1.0
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Superset Kubernetes documentation resource offline
2 participants