The website currently has the following redirect patterns that are implemented in a .htaccess file. The source for this file is found in the docs/build_version_docs/artifacts folder.

Using an environment var for the default version, we can flag it throughout the htaccess file:

RewriteRule .* - [E=default_version:/versions/master]

Then we use this variable with:


Current Implementation

The first entity is the pattern to match, the second is the destination, and the third is a test URL. Prod for now doesn't use the default version and just redirects to the root. 

Our current default version is master. Either way the default version should be recent information. Queries to old pages are redirected.

Legacy URLsNew URL (desired redirect)Prod Test URLStaging Test URL











The goal for the following section is that any request to a resource of an old version is redirected to the default version. should go to

Content that should be freshNew URL (desired redirect)Prod Test URLStaging Test URL



















API test - this should load older content then switch versions to master. It should keep the anchor in the url.

Note that tutorials will carry the request for the particular tutorial over to the default version. Also, since some of the install links can carry a specific install type it might be good to add $1 to that one.

Possible expression to capture the requests listed above and meet the overall goals:

  1. Make sure requests to "root" resources go to /versions/master/$REQUEST
  2. Make sure requests to old version resource go to /versions/master/$REQUEST
  3. Allow requests on /api docs to go to the old version pages
  4. Search requests on old versions should work


Redirect APIs that did not exist

Finally, we have several pages for API that don't exist and it is possible for the user to navigate to them. Instead of a broken page we give them a nice 404 or error message.

^versions/0.11.0/api/python/contrib/onnx.html /error/api.html
^versions/0.12.1/api/python/contrib/onnx.html /error/api.html
^versions/1.0.0/api/python/contrib/onnx.html /error/api.html
^versions/1.1.0/api/python/contrib/onnx.html /error/api.html

Test URL:

Test URL:

^versions/0.11.0/api/clojure/.*$ /error/api.html
^versions/0.12.1/api/clojure/.*$ /error/api.html
^versions/1.0.0/api/clojure/.*$ /error/api.html
^versions/1.1.0/api/clojure/.*$ /error/api.html
^versions/1.2.1/api/clojure/.*$ /error/api.html

Test URL:

Test URL:

Error Pages

ErrorDocument 404

For all other APIs it should allow the queries to go through.

Error Redirect Issues

The error redirect uses a full URL instead of a local one because otherwise the error page doesn't render properly. 

Given a relative local URL like /error/404.html the error page mostly fails to render properly. If the page that didn't exist is, for example, /1/2/3/4/index.html, then the URL will be kept as such, but the 404 page will be rendered as if it is in /1/2/3/4/. The js, css, and other assets will still have URLs expecting the page to be rendered at /error/404.html, so all of those assets 404 and thus a massive fail. This could potentially be fixed by making a custom page outside of the Sphinx theme, but at this point the URLs are generated and relative to the error page's actual location.

The drawback of using a full URL is that the HTTP header shows 302, not 404. This will confuse robots into thinking that the page does exist, and it is just in a new location. Instead we really should be giving a 404.

One approach could be to fix the theme issue as mentioned above or somehow exempt the error page from regular Sphinx theming. Then the local URL could be used.

Testing Redirects

Use the following curl example from command line to see the redirect's output without having to use the browser!

curl -sSL -D - -o /dev/null

  • No labels