Envoy: Broken documentation links

[bcelenza]

I've observed a number of broken links in Envoy documentation that previously worked (now showing a 404). Examples:

• https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/http/websocket (referenced from a google search of "envoy proxy web socket")
• https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log (referenced from other documentation on the internet)

It appears we're knowingly breaking these links without any sort of redirect to the new location. What's the policy for the Envoy site in this regard? Breaking existing links has an unfortunate chain-reaction effect on any product that relies on Envoy, and all Envoy users.

[mattklein123]

We don't have any policy on this currently, and no good way to enforce/check changes/add redirects given how docs get built with sphinx. Would appreciate help on this if there is interest. Will mark help wanted.

[mk46]

Hi @mattklein123, Actual redirection for both links should be

• https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/http/upgrades
• https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/observability/access_logging

In readthedocs UI, there is an option for "redirect" in the admin section.

[mattklein123]

Tooling PRs appreciated to help us do better here. Thank you!

[phlax]

@mattklein123 i can take a look at this

[phlax]

i dont think we host the docs on readthedocs - afaict the docs are hosted in github pages from a repo here https://github.com/envoyproxy/envoyproxy.github.io - and there doesnt seem to be a way to add stubs/redirects in sphinx.

im wondering if we can do it with jekyll, somehow

[phlax]

i take that back - you can add redirects in sphinx i think https://github.com/sphinx-contrib/redirects

[phlax]

if we are going to move things around in the main doc tree, i think we will need to have this working first (#13386)

[phlax]

this might be a better option https://github.com/wpilibsuite/sphinxext-rediraffe - its supported on pypi, dev seems more active, and has a diffchecker tool to ensure re/moved pages have redirects