Fix all the redirects!

## The problems Today, //site/docs/index.md is a redirect to https://docs.bazel.build/versions/3.2.0/bazel-overview.html (because 3.2.0 is the latest release version). This seems fine until you remember that //site/docs/index.md does *not* represent https://docs.bazel.build/index.html, rather https://docs.bazel.build/versions/$ANY_VERSION/index.html ! This means that, for example, even https://docs.bazel.build/versions/2.1.0/index.html will point to the 3.2.0 landing page. Not great. To make matters more confusing, https://docs.bazel.build/$SOME_PATH is automatically redirected to https://docs.bazel.build/versions/master/$SOME_PATH . This seems undesirable since we want unversioned URLs to redirect to the latest release version, not master. But wait, how come the home page isn't broken? https://docs.bazel.build/index.html redirects to https://docs.bazel.build/versions/master/index.html, which -- thanks to the problem described in the first paragraph -- redirects again to https://docs.bazel.build/versions/3.2.0/bazel-overview.html . It ends up working by a fluke! Furthermore, //site/docs/index.md, being a markdown file, contains raw HTML. This is actually a subtle time bomb since its indented HTML formatting is incompatible with the popular GitHub flavored markdown, which is the reason why the previous attempt to switch to GFM caused a home page outage. ## The fix For the first problem, we change //site/docs/index.md to be a redirect to the relative path "bazel-overview.html", which means that the 2.1.0 version of index.html will point to the 2.1.0 version of bazel-overview.html. For the second problem, we change //site/jekyll-tree.sh to always make the root directory redirects point at the latest released version, instead of master. For the third problem, we simply make //site/docs/index.md use the redirect layout (this is now possible since we don't have a variable in the redirect target anymore). It's now compatible with *any* markdown format, since it's empty. Perfect! RELNOTES: PiperOrigin-RevId: 313735647
bazelbuild · May 29, 2020 · 565f774 · 565f774
1 parent acab2c2
commit 565f774
Show file tree

Hide file tree

Showing 4 changed files with 24 additions and 22 deletions.
diff --git a/site/BUILD b/site/BUILD
@@ -150,6 +150,7 @@ genrule(
     ],
     outs = ["jekyll-tree.tar"],
     cmd = ("$(location jekyll-tree.sh) $@ " +
+           DOC_VERSIONS[0]["version"].split("-")[0] + " " +
            "$(location :jekyll-base) " +
            "$(location :skylark-rule-docs) " +
            "$(location //src/main/java/com/google/devtools/build/lib:gen_buildencyclopedia) " +

diff --git a/site/_layouts/redirect.html b/site/_layouts/redirect.html
@@ -3,5 +3,7 @@
     <script>
       window.location.replace("{{ page.redirect }}" + window.location.hash);
     </script>
+    <!-- Fall back to a <meta> redirect if the user has JavaScript disabled. -->
+    <meta http-equiv="refresh" content="0;url={{ page.redirect }}">
   </head>
-</html>
+</html>
diff --git a/site/docs/index.md b/site/docs/index.md
@@ -1,10 +1,4 @@
 ---
+layout: redirect
+redirect: bazel-overview.html
 ---
-
-<html>
-  <head>
-    <script>
-      window.location.replace("/versions/{{ site.version }}/bazel-overview.html");
-    </script>
-  </head>
-</html>
diff --git a/site/jekyll-tree.sh b/site/jekyll-tree.sh
@@ -17,14 +17,17 @@
 # site files with generated documentation, such as the Build Encyclopedia and
 # Starlark Library. It then constructs the site directory structure for
 # Bazel documentation at HEAD by moving all documentation into the
-# /versions/master directory and adding redirects from the root of the site.
-# This way, URLs of the form https://docs.bazel.build/foo.html will be
-# redirected to https://docs.bazel.build/versions/master/foo.html.
+# /versions/$VERSION directory and adding redirects from the root of the site to
+# the latest released version. This way, URLs of the form
+# https://docs.bazel.build/foo.html will be redirected to
+# https://docs.bazel.build/versions/$LATEST_RELEASE_VERSION/foo.html.
 
 set -eu
 
 readonly OUTPUT=${PWD}/$1
 shift
+readonly LATEST_RELEASE_VERSION=$1
+shift
 readonly JEKYLL_BASE=${PWD}/$1
 shift
 readonly STARLARK_RULE_DOCS=${PWD}/$1
@@ -55,19 +58,19 @@ function setup {
   mv "$OUT_DIR"/docs/* "$VERSION_DIR"
   rm -r "$OUT_DIR"/docs
 
-  # Unpack the Build Encyclopedia into versions/master/be
+  # Unpack the Build Encyclopedia into versions/$VERSION/be
   local be_dir="$VERSION_DIR/be"
   mkdir -p "$be_dir"
   unzip -qq "$BE_ZIP" -d "$be_dir"
   mv "$be_dir/be-nav.html" "$OUT_DIR/_includes"
 
-  # Unpack the Starlark Library into versions/master/skylark/lib
+  # Unpack the Starlark Library into versions/$VERSION/skylark/lib
   local sl_dir="$VERSION_DIR/skylark/lib"
   mkdir -p "$sl_dir"
   unzip -qq "$SL_ZIP" -d "$sl_dir"
   mv "$sl_dir/skylark-nav.html" "$OUT_DIR/_includes"
 
-  # Unpack the documentation for the repository rules to repo subdirectory
+  # Unpack the documentation for the repository rules to versions/$VERSION/repo
   local repo_dir="${VERSION_DIR}/repo"
   mkdir -p "${repo_dir}"
   tar -C "${repo_dir}" -xf "${REPO_TAR}"
@@ -121,7 +124,8 @@ function process_docs {
   done
 }
 
-# Generates a redirect for a documentation page under /versions/master.
+# Generates a redirect for a documentation page under
+# /versions/$LATEST_RELEASE_VERSION.
 function gen_redirect {
   local output_dir=$OUT_DIR/$(dirname $f)
   if [[ ! -d "$output_dir" ]]; then
@@ -139,17 +143,18 @@ function gen_redirect {
   cat > "$redirect_file" <<EOF
 ---
 layout: redirect
-redirect: /versions/$VERSION/$html_file
+redirect: /versions/$LATEST_RELEASE_VERSION/$html_file
 ---
 EOF
 }
 
-# During setup, all documentation under docs are moved to the /versions/master
-# directory as the documentation from HEAD.
+# During setup, all documentation under docs are moved to the /versions/$VERSION
+# directory. This leaves nothing in the root directory.
 #
-# This function henerates a redirect from the root of the site for the given
-# doc page under /versions/master so that https://docs.bazel.build/foo.html
-# will be redirected to https://docs.bazel.build/versions/master/foo.html
+# This function generates a redirect from the root of the site for the given
+# doc page under /versions/$LATEST_RELEASE_VERSION so that
+# https://docs.bazel.build/foo.html will be redirected to
+# https://docs.bazel.build/versions/$LATEST_RELEASE_VERSION/foo.html
 function gen_redirects {
   pushd "$VERSION_DIR" > /dev/null
   for f in $(find . -name "*.html" -type f); do