Repository: bazelbuild/bazel
Issue: Versioning for Bazel docs
Labels: type: documentation (cleanup)
P2
team-Bazel

The docs on bazel.io are synced with `master`, and updates are pushed when new commits are pushed to `master`. As a result, the docs are often ahead of the latest release. We should also add versioning for the Bazel docs for releases. This is also something that @damienmg brought up in a separate thread offline.

The documentation should also note which version they are for.


Issue comments:
To sort of reiterate a comment I made on bazel-discuss (possibly redundant, as I'm not sure what "add versioning" means), it would be helpful if:

- The docs prominently display the Bazel version to which they apply.
- Docs for multiple versions, including `master` are readily available (e.g. see Python docs, Qt docs, ...)
- The default version displayed is *the latest stable release*.
- The site sets a cookie so that the last viewed version is displayed when the user comes back.

As a stop-gap, it would be nice if the main documentation was for the latest release, with the "bleeding edge" documentation published somewhere less obvious or less "official".

Pull request review comments:
What are these hashes?
How do we update them?
why do we need `exit` at the end?

If it's because of the trap, can you instead put the `mv` here?
Or put the `sed` only when the condition is true?
Add comment that it must be in sync with the config file?
good idea. fixed.
added instructions on what they are and how to get them.

Patch that resolved the issue:
diff --git a/WORKSPACE b/WORKSPACE
index ef6fb686911873..907c1bb7de423b 100644
--- a/WORKSPACE
+++ b/WORKSPACE
@@ -278,3 +278,11 @@ distdir_tar(
       "jdk10-server-release-1804.tar.xz" : ["https://mirror.bazel.build/openjdk.linaro.org/releases/jdk10-server-release-1804.tar.xz"],
   },
 )
+
+load("//scripts/docs:doc_versions.bzl", "DOC_VERSIONS")
+
+[http_file(
+    name = "jekyll_tree_%s" % DOC_VERSION["version"].replace(".", "_"),
+    sha256 = DOC_VERSION["sha256"],
+    urls = ["https://mirror.bazel.build/bazel_versioned_docs/jekyll-tree-%s.tar" % DOC_VERSION["version"]],
+) for DOC_VERSION in DOC_VERSIONS]
diff --git a/scripts/docs/doc_versions.bzl b/scripts/docs/doc_versions.bzl
new file mode 100644
index 00000000000000..6ce903f37efb9f
--- /dev/null
+++ b/scripts/docs/doc_versions.bzl
@@ -0,0 +1,34 @@
+# To get the checksum of the versioned documentation tree tarball, run the
+# following command with the selected Bazel version:
+#
+# $ curl -s https://mirror.bazel.build/bazel_versioned_docs/jekyll-tree-0.20.0.tar | sha256sum | cut -d" " -f1
+# bb79a63810bf1b0aa1f89bd3bbbeb4a547a30ab9af70c9be656cc6866f4b015b
+#
+# This list must be kept in sync with `doc_versions` variable in //site:_config.yml
+
+DOC_VERSIONS = [
+    {
+        "version": "0.20.0",
+        "sha256": "bb79a63810bf1b0aa1f89bd3bbbeb4a547a30ab9af70c9be656cc6866f4b015b",
+    },
+    {
+        "version": "0.19.2",
+        "sha256": "3c2d9f21ec2fd1c0b8a310f6eb6043027c838810cdfc2457d4346a0e5cdcaa7a",
+    },
+    {
+        "version": "0.19.1",
+        "sha256": "ec892c59ba18bb8de1f9ae2bde937db144e45f28d6d1c32a2cee847ee81b134d",
+    },
+    {
+        "version": "0.18.1",
+        "sha256": "98b77f48e37a50fc6f83100bf53f661e10732bb3ddbc226e02d0225cb7a9a7d8",
+    },
+    {
+        "version": "0.17.2",
+        "sha256": "13b35dd309a0d52f0a2518a1193f42729c75255f5fae40cea68e4d4224bfaa2e",
+    },
+    {
+        "version": "0.17.1",
+        "sha256": "02256ddd20eeaf70cf8fcfe9b2cdddd7be87aedd5848d549474fb0358e0031d3",
+    },
+]
diff --git a/scripts/docs/generate_versioned_docs.sh b/scripts/docs/generate_versioned_docs.sh
new file mode 100755
index 00000000000000..8be787aa246800
--- /dev/null
+++ b/scripts/docs/generate_versioned_docs.sh
@@ -0,0 +1,55 @@
+#!/bin/bash
+
+# Generate a versioned documentation tree.
+#
+# Run this script from a git checkout of a release tag. This script will infer
+# the tag and create the documentation tree with the correct tag injected into
+# the static pages, archive the tree, and copy it to Google Cloud Storage.
+#
+# This only needs to be done once per release. This script is non-destructive.
+#
+# TODO(jingwen): Automate this into the release pipeline.
+
+set -eu
+
+function log_info() {
+  echo "[Info]" $@
+}
+
+readonly SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+# Unless we're in a tag (e.g. 0.20.0), set DOC_VERSION to master.
+readonly DOC_VERSION=$(git describe --tags --exact-match 2>/dev/null || echo "NOT_A_RELEASE")
+
+if [[ $DOC_VERSION == "NOT_A_RELEASE" ]]
+then
+  log_info "You are currently in the branch: `git rev-parse --abbrev-ref HEAD`"
+  log_info "Please run this script from a git checkout of a release tag, e.g. git checkout 0.20.0"
+  log_info "See the valid list of tags with 'git tag'"
+  exit 1
+fi
+
+function cleanup() {
+  mv $SCRIPT_DIR/../../site/_config.yml{.bak,}
+}
+
+read -p "You're going to generate the docs for $DOC_VERSION. Continue? <y/n> " prompt
+if [[ $prompt =~ [yY](es)* ]]
+then
+  # Modify the "version" Jekyll variable so all links in anchor tags are generated
+  # with the injected version.
+  sed -i.bak "s/master/$DOC_VERSION/" $SCRIPT_DIR/../../site/_config.yml
+  trap cleanup EXIT
+
+  bazel build //site:jekyll-tree --action_env=DOC_VERSION=$DOC_VERSION
+
+  # -n: no-clobber; prevent overwriting existing archives to be non-destructive.
+  # There should be no need to delete existing archives once it's uploaded. But
+  # should there be such a need, please file an issue.
+  #
+  # -a public-read: set the default ACL for uploaded archives to public-read for Bazel to download it.
+  gsutil cp -n -a public-read $SCRIPT_DIR/../../bazel-genfiles/site/jekyll-tree.tar gs://bazel-mirror/bazel_versioned_docs/jekyll-tree-$DOC_VERSION.tar
+
+  log_info "Done."
+  log_info "Now, please add \"$DOC_VERSION\" to the doc_versions list in <workspace>/site/_config.yml."
+  log_info "Please also add \"$DOC_VERSION\" to <workspace>/scripts/docs/doc_versions.bzl."
+fi
diff --git a/site/BUILD b/site/BUILD
index 370ef7e085fd68..782c5994eda2e7 100644
--- a/site/BUILD
+++ b/site/BUILD
@@ -1,5 +1,6 @@
 load("//tools/build_defs/pkg:pkg.bzl", "pkg_tar")
 load("//scripts/docs:jekyll.bzl", "jekyll_build")
+load("//scripts/docs:doc_versions.bzl", "DOC_VERSIONS")
 
 exports_files(
     [
@@ -125,6 +126,7 @@ tar cf $$origdir/$@ *
     tools = ["//scripts/docs:generate_dot_graphs"],
 )
 
+# Generate the documentation tree in the current git worktree
 genrule(
     name = "jekyll-tree",
     srcs = [
@@ -148,6 +150,9 @@ genrule(
 
 jekyll_build(
     name = "site",
-    srcs = [":jekyll-tree"],
+    srcs = [
+        "@jekyll_tree_%s//file" % DOC_VERSION["version"].replace(".", "_")
+        for DOC_VERSION in DOC_VERSIONS
+    ] + [":jekyll-tree"],  # jekyll-tree *must* come last to be the default.
     bucket = "docs.bazel.build",
 )
diff --git a/site/_config.yml b/site/_config.yml
index a57a92b4b6816e..00f82998f49c69 100644
--- a/site/_config.yml
+++ b/site/_config.yml
@@ -12,6 +12,16 @@ gems: [jekyll-paginate]
 
 version: "master"
 
+# This must be kept in sync with //site/script/docs:versions.bzl
+doc_versions:
+  - master
+  - 0.20.0
+  - 0.19.2
+  - 0.19.1
+  - 0.18.1
+  - 0.17.2
+  - 0.17.1
+
 main_site_url: https://www.bazel.build
 docs_site_url: "/"
 blog_site_url: https://blog.bazel.build
diff --git a/site/_layouts/documentation.html b/site/_layouts/documentation.html
index 10f3b669432bd5..0ac8e3440f2cb7 100644
--- a/site/_layouts/documentation.html
+++ b/site/_layouts/documentation.html
@@ -22,16 +22,31 @@ <h1>Documentation</h1>
               aria-controls="sidebar-nav">
             <i class="glyphicon glyphicon-menu-hamburger"></i> Navigation
           </a>
+
           <nav class="sidebar collapse" id="sidebar-nav">
-           <h3>Home</h3>
+            <!-- /versions/master/foo/bar -> ["master", "foo", "bar"] -->
+            <!-- /versions/0.12.3/baz.md -> ["0.12.3", "baz.md"] -->
+            {% assign versioned_url_parts = page.url | split: '/' | shift | shift %}
+            {% assign current_version = versioned_url_parts.first %}
+            <select onchange="location.href=this.value">
+                <option value="" selected disabled hidden>Version: {{ current_version }}</option>
+                {% for doc_version in site.doc_versions %}
+                <!-- reconstruct absolute url for the current page for each doc version -->
+                <option value="/{{ versioned_url_parts | shift | unshift: doc_version | unshift: 'versions' | join: '/' }}">
+                    {{ doc_version }}
+                </option>
+                {% endfor %}
+            </select>
+
+            <h3>Home</h3>
             <ul class="sidebar-nav">
-              <li><a href="/versions/{{ site.version }}/bazel-overview.html">Bazel Overview</a></li>
-              <li><a href="/versions/{{ site.version }}/bazel-vision.html">Bazel Vision</a></li>
-              <li><a href="/versions/{{ site.version }}/getting-started.html">Getting Started</a></li>
-              <li><a href="/versions/{{ site.version }}/skylark/backward-compatibility.html">Backward Compatibility</a></li>
+              <li><a href="/versions/{{ current_version }}/bazel-overview.html">Bazel Overview</a></li>
+              <li><a href="/versions/{{ current_version }}/bazel-vision.html">Bazel Vision</a></li>
+              <li><a href="/versions/{{ current_version }}/getting-started.html">Getting Started</a></li>
+              <li><a href="/versions/{{ current_version }}/skylark/backward-compatibility.html">Backward Compatibility</a></li>
             </ul>
 
-           <h3>Using Bazel</h3>
+            <h3>Using Bazel</h3>
             <ul class="sidebar-nav">
 
               <li>
@@ -41,14 +56,14 @@ <h3>Using Bazel</h3>
                   Installing Bazel<span class="caret"></span>
                 </a>
                 <ul class="collapse sidebar-nav sidebar-submenu" id="installing-menu">
-                   <li><a href="/versions/{{ site.version }}/install.html">Installation Overview</a></li>
-                   <li><a href="/versions/{{ site.version }}/install-ubuntu.html">Installing on Ubuntu</a></li>
-                   <li><a href="/versions/{{ site.version }}/install-redhat.html">Installing on Fedora/CentOS</a></li>
-                   <li><a href="/versions/{{ site.version }}/install-os-x.html">Installing on macOS</a></li>
-                   <li><a href="/versions/{{ site.version }}/install-windows.html">Installing on Windows</a></li>
-                   <li><a href="/versions/{{ site.version }}/install-compile-source.html">Compiling from Source</a></li>
-                   <li><a href="/versions/{{ site.version }}/completion.html">Command-Line Completion</a></li>
-                   <li><a href="/versions/{{ site.version }}/ide.html">Integrating with IDEs</a></li>
+                   <li><a href="/versions/{{ current_version }}/install.html">Installation Overview</a></li>
+                   <li><a href="/versions/{{ current_version }}/install-ubuntu.html">Installing on Ubuntu</a></li>
+                   <li><a href="/versions/{{ current_version }}/install-redhat.html">Installing on Fedora/CentOS</a></li>
+                   <li><a href="/versions/{{ current_version }}/install-os-x.html">Installing on macOS</a></li>
+                   <li><a href="/versions/{{ current_version }}/install-windows.html">Installing on Windows</a></li>
+                   <li><a href="/versions/{{ current_version }}/install-compile-source.html">Compiling from Source</a></li>
+                   <li><a href="/versions/{{ current_version }}/completion.html">Command-Line Completion</a></li>
+                   <li><a href="/versions/{{ current_version }}/ide.html">Integrating with IDEs</a></li>
                  </ul>
                 </li>
 
@@ -59,18 +74,18 @@ <h3>Using Bazel</h3>
                   Tutorials<span class="caret"></span>
                 </a>
                 <ul class="collapse sidebar-nav sidebar-submenu" id="tutorials-menu">
-                   <li><a href="/versions/{{ site.version }}/tutorial/java.html">Building a Java Project</a></li>
-                   <li><a href="/versions/{{ site.version }}/tutorial/cpp.html">Building a C++ Project</a></li>
-                   <li><a href="/versions/{{ site.version }}/tutorial/android-app.html">Building an Android App</a></li>
-                   <li><a href="/versions/{{ site.version }}/tutorial/ios-app.html">Building an iOS App</a></li>
-                   <li><a href="/versions/{{ site.version }}/skylark/tutorial-sharing-variables.html">Sharing Variables</a></li>
-                   <li><a href="/versions/{{ site.version }}/skylark/tutorial-creating-a-macro.html">Creating a Macro</a></li>
+                   <li><a href="/versions/{{ current_version }}/tutorial/java.html">Building a Java Project</a></li>
+                   <li><a href="/versions/{{ current_version }}/tutorial/cpp.html">Building a C++ Project</a></li>
+                   <li><a href="/versions/{{ current_version }}/tutorial/android-app.html">Building an Android App</a></li>
+                   <li><a href="/versions/{{ current_version }}/tutorial/ios-app.html">Building an iOS App</a></li>
+                   <li><a href="/versions/{{ current_version }}/skylark/tutorial-sharing-variables.html">Sharing Variables</a></li>
+                   <li><a href="/versions/{{ current_version }}/skylark/tutorial-creating-a-macro.html">Creating a Macro</a></li>
                  </ul>
               </li>
 
-              <li><a href="/versions/{{ site.version }}/build-ref.html">Bazel Concepts</a></li>
-              <li><a href="/versions/{{ site.version }}/guide.html">User's Guide</a></li>
-              <li><a href="/versions/{{ site.version }}/external.html">External Dependencies</a></li>
+              <li><a href="/versions/{{ current_version }}/build-ref.html">Bazel Concepts</a></li>
+              <li><a href="/versions/{{ current_version }}/guide.html">User's Guide</a></li>
+              <li><a href="/versions/{{ current_version }}/external.html">External Dependencies</a></li>
 
               <li>
                 <a class="sidebar-nav-heading" data-toggle="collapse"
@@ -79,15 +94,15 @@ <h3>Using Bazel</h3>
                   Queries<span class="caret"></span>
                 </a>
                 <ul class="collapse sidebar-nav sidebar-submenu" id="query-menu">
-                  <li><a href="/versions/{{ site.version }}/query-how-to.html">Bazel query</a></li>
-                  <li><a href="/versions/{{ site.version }}/cquery.html">Bazel cquery</a></li>
-                  <li><a href="/versions/{{ site.version }}/user-manual.html#aquery">Bazel aquery</a></li>
-                  <li><a href="/versions/{{ site.version }}/query.html">Query Language</a></li>
+                  <li><a href="/versions/{{ current_version }}/query-how-to.html">Bazel query</a></li>
+                  <li><a href="/versions/{{ current_version }}/cquery.html">Bazel cquery</a></li>
+                  <li><a href="/versions/{{ current_version }}/user-manual.html#aquery">Bazel aquery</a></li>
+                  <li><a href="/versions/{{ current_version }}/query.html">Query Language</a></li>
                 </ul>
               </li>
 
-              <li><a href="/versions/{{ site.version }}/configurable-attributes.html">Configurable Attributes</a></li>
-              <li><a href="/versions/{{ site.version }}/best-practices.html">Best Practices</a></li>
+              <li><a href="/versions/{{ current_version }}/configurable-attributes.html">Configurable Attributes</a></li>
+              <li><a href="/versions/{{ current_version }}/best-practices.html">Best Practices</a></li>
               <li>
                 <a class="sidebar-nav-heading" data-toggle="collapse"
                     href="#remote-execution-menu" aria-expanded="false"
@@ -95,8 +110,8 @@ <h3>Using Bazel</h3>
                   Remote Execution<span class="caret"></span>
                 </a>
                 <ul class="collapse sidebar-nav sidebar-submenu" id="remote-execution-menu">
-                   <li><a href="/versions/{{ site.version }}/remote-execution.html">Remote Execution Overview</a></li>
-                   <li><a href="/versions/{{ site.version }}/remote-execution-rules.html">Guidelines for Remote Execution</a></li>
+                   <li><a href="/versions/{{ current_version }}/remote-execution.html">Remote Execution Overview</a></li>
+                   <li><a href="/versions/{{ current_version }}/remote-execution-rules.html">Guidelines for Remote Execution</a></li>
                    <li>
                       <a class="sidebar-nav-heading" data-toggle="collapse"
                           href="#troubleshoot-remote-execution-menu" aria-expanded="false"
@@ -104,12 +119,12 @@ <h3>Using Bazel</h3>
                         Troubleshooting Remote Execution<span class="caret"></span>
                       </a>
                       <ul class="collapse sidebar-nav sidebar-submenu" id="troubleshoot-remote-execution-menu">
-                         <li><a href="/versions/{{ site.version }}/remote-execution-sandbox.html">Troubleshooting Remote Execution with Bazel Sandbox</a></li>
-                         <li><a href="/versions/{{ site.version }}/workspace-log.html">Finding non-hermetic behavior in WORKSPACE rules</a></li>
-                         <li><a href="/versions/{{ site.version }}/remote-execution-caching-debug.html">Debugging Remote Cache Hit Rate</a></li>
+                         <li><a href="/versions/{{ current_version }}/remote-execution-sandbox.html">Troubleshooting Remote Execution with Bazel Sandbox</a></li>
+                         <li><a href="/versions/{{ current_version }}/workspace-log.html">Finding non-hermetic behavior in WORKSPACE rules</a></li>
+                         <li><a href="/versions/{{ current_version }}/remote-execution-caching-debug.html">Debugging Remote Cache Hit Rate</a></li>
                       </ul>
                   </li>
-                   <li><a href="/versions/{{ site.version }}/remote-execution-ci.html">Configuring Bazel CI for Remote Execution Rule Testing</a></li>
+                   <li><a href="/versions/{{ current_version }}/remote-execution-ci.html">Configuring Bazel CI for Remote Execution Rule Testing</a></li>
                  </ul>
               </li>
 
@@ -120,15 +135,15 @@ <h3>Using Bazel</h3>
                     Remote Caching<span class="caret"></span>
                   </a>
                   <ul class="collapse sidebar-nav sidebar-submenu" id="remote-caching-menu">
-                     <li><a href="/versions/{{ site.version }}/remote-caching.html">Remote Caching Overview</a></li>
-                     <li><a href="/versions/{{ site.version }}/remote-caching-debug.html">Debugging Remote Cache Hit Rate for Local Execution</a></li>
+                     <li><a href="/versions/{{ current_version }}/remote-caching.html">Remote Caching Overview</a></li>
+                     <li><a href="/versions/{{ current_version }}/remote-caching-debug.html">Debugging Remote Cache Hit Rate for Local Execution</a></li>
                   </ul>
               </li>
              </ul>
 
            <h3>Rules</h3>
            <ul class="sidebar-nav">
-             <li><a href="/versions/{{ site.version }}/be/overview.html">Build Encyclopedia</a></li>
+             <li><a href="/versions/{{ current_version }}/be/overview.html">Build Encyclopedia</a></li>
 
               <li>
                 <a class="sidebar-nav-heading" data-toggle="collapse"
@@ -137,10 +152,10 @@ <h3>Rules</h3>
                   Android<span class="caret"></span>
                 </a>
                 <ul class="collapse sidebar-nav sidebar-submenu" id="android-menu">
-                  <li><a href="/versions/{{ site.version }}/bazel-and-android.html">Android Resources</a></li>
-                  <li><a href="/versions/{{ site.version }}/mobile-install.html">Using mobile-install</a></li>
-                  <li><a href="/versions/{{ site.version }}/android-instrumentation-test.html">Android Instrumentation Tests</a></li>
-                  <li><a href="/versions/{{ site.version }}/android-ndk.html">Android NDK</a></li>
+                  <li><a href="/versions/{{ current_version }}/bazel-and-android.html">Android Resources</a></li>
+                  <li><a href="/versions/{{ current_version }}/mobile-install.html">Using mobile-install</a></li>
+                  <li><a href="/versions/{{ current_version }}/android-instrumentation-test.html">Android Instrumentation Tests</a></li>
+                  <li><a href="/versions/{{ current_version }}/android-ndk.html">Android NDK</a></li>
                   <li><a href="https://plugins.jetbrains.com/plugin/9185-bazel">Android Studio Plugin</a></li>
                 </ul>
               </li>
@@ -152,9 +167,9 @@ <h3>Rules</h3>
                   Apple<span class="caret"></span>
                 </a>
                 <ul class="collapse sidebar-nav sidebar-submenu" id="apple-menu">
-                  <li><a href="/versions/{{ site.version }}/bazel-and-apple.html">Apple Resources</a></li>
-                  <li><a href="/versions/{{ site.version }}/migrate-xcode.html">Migrating from Xcode</a></li>
-                  <li><a href="/versions/{{ site.version }}/migrate-cocoapods.html">Converting CocoaPods</a></li>
+                  <li><a href="/versions/{{ current_version }}/bazel-and-apple.html">Apple Resources</a></li>
+                  <li><a href="/versions/{{ current_version }}/migrate-xcode.html">Migrating from Xcode</a></li>
+                  <li><a href="/versions/{{ current_version }}/migrate-cocoapods.html">Converting CocoaPods</a></li>
                 </ul>
               </li>
 
@@ -165,10 +180,10 @@ <h3>Rules</h3>
                   C++<span class="caret"></span>
                 </a>
                 <ul class="collapse sidebar-nav sidebar-submenu" id="cpp-menu">
-                  <li><a href="/versions/{{ site.version }}/bazel-and-cpp.html">C++ Resources</a></li>
-                  <li><a href="/versions/{{ site.version }}/cpp-use-cases.html">C++ Use Cases</a></li>
-                  <li><a href="/versions/{{ site.version }}/crosstool-reference.html">Understanding CROSSTOOL</a></li>
-                  <li><a href="/versions/{{ site.version }}/tutorial/crosstool.html">Tutorial: CROSSTOOL</a></li>
+                  <li><a href="/versions/{{ current_version }}/bazel-and-cpp.html">C++ Resources</a></li>
+                  <li><a href="/versions/{{ current_version }}/cpp-use-cases.html">C++ Use Cases</a></li>
+                  <li><a href="/versions/{{ current_version }}/crosstool-reference.html">Understanding CROSSTOOL</a></li>
+                  <li><a href="/versions/{{ current_version }}/tutorial/crosstool.html">Tutorial: CROSSTOOL</a></li>
                 </ul>
               </li>
 
@@ -179,9 +194,9 @@ <h3>Rules</h3>
                   Java<span class="caret"></span>
                 </a>
                 <ul class="collapse sidebar-nav sidebar-submenu" id="java-menu">
-                  <li><a href="/versions/{{ site.version }}/bazel-and-java.html">Java Resources</a></li>
-                  <li><a href="/versions/{{ site.version }}/migrate-maven.html">Migrating from Maven</a></li>
-                  <li><a href="/versions/{{ site.version }}/generate-workspace.html">Converting Maven Dependencies</a></li>
+                  <li><a href="/versions/{{ current_version }}/bazel-and-java.html">Java Resources</a></li>
+                  <li><a href="/versions/{{ current_version }}/migrate-maven.html">Migrating from Maven</a></li>
+                  <li><a href="/versions/{{ current_version }}/generate-workspace.html">Converting Maven Dependencies</a></li>
                 </ul>
               </li>
 
@@ -192,8 +207,8 @@ <h3>Rules</h3>
                   JavaScript<span class="caret"></span>
                 </a>
                 <ul class="collapse sidebar-nav sidebar-submenu" id="javascript-menu">
-                  <li><a href="/versions/{{ site.version }}/bazel-and-javascript.html">JavaScript Resources</a></li>
-                  <li><a href="/versions/{{ site.version }}/build-javascript.html">Building JavaScript</a></li>
+                  <li><a href="/versions/{{ current_version }}/bazel-and-javascript.html">JavaScript Resources</a></li>
+                  <li><a href="/versions/{{ current_version }}/build-javascript.html">Building JavaScript</a></li>
                 </ul>
               </li>
 
@@ -201,19 +216,19 @@ <h3>Rules</h3>
 
            <h3>Reference</h3>
            <ul class="sidebar-nav">
-             <li><a href="/versions/{{ site.version }}/user-manual.html">Commands and Options</a></li>
-             <li><a href="/versions/{{ site.version }}/skylark/build-style.html">BUILD Style Guide</a></li>
-             <li><a href="/versions/{{ site.version }}/command-line-reference.html">Command Line Reference</a></li>
-             <li><a href="/versions/{{ site.version }}/test-encyclopedia.html">Writing Tests</a></li>
-             <li><a href="/versions/{{ site.version }}/build-event-protocol.html">Build Event Protocol</a></li>
-             <li><a href="/versions/{{ site.version }}/output_directories.html">Output Directory Layout</a></li>
-             <li><a href="/versions/{{ site.version }}/platforms.html">Platforms</a></li>
-             <li><a href="/versions/{{ site.version }}/toolchains.html">Toolchains</a></li>
+             <li><a href="/versions/{{ current_version }}/user-manual.html">Commands and Options</a></li>
+             <li><a href="/versions/{{ current_version }}/skylark/build-style.html">BUILD Style Guide</a></li>
+             <li><a href="/versions/{{ current_version }}/command-line-reference.html">Command Line Reference</a></li>
+             <li><a href="/versions/{{ current_version }}/test-encyclopedia.html">Writing Tests</a></li>
+             <li><a href="/versions/{{ current_version }}/build-event-protocol.html">Build Event Protocol</a></li>
+             <li><a href="/versions/{{ current_version }}/output_directories.html">Output Directory Layout</a></li>
+             <li><a href="/versions/{{ current_version }}/platforms.html">Platforms</a></li>
+             <li><a href="/versions/{{ current_version }}/toolchains.html">Toolchains</a></li>
            </ul>
 
             <h3>Extending Bazel</h3>
            <ul class="sidebar-nav">
-              <li><a href="/versions/{{ site.version }}/skylark/concepts.html">Extension Overview</a></li>
+              <li><a href="/versions/{{ current_version }}/skylark/concepts.html">Extension Overview</a></li>
 
               <li>
                 <a class="sidebar-nav-heading" data-toggle="collapse"
@@ -222,12 +237,12 @@ <h3>Extending Bazel</h3>
                   Concepts<span class="caret"></span>
                 </a>
                 <ul class="collapse sidebar-nav sidebar-submenu" id="starlark-concepts">
-                  <li><a href="/versions/{{ site.version }}/skylark/macros.html">Macros</a></li>
-                  <li><a href="/versions/{{ site.version }}/skylark/rules.html">Rules</a></li>
-                  <li><a href="/versions/{{ site.version }}/skylark/depsets.html">Depsets</a></li>
-                  <li><a href="/versions/{{ site.version }}/skylark/aspects.html">Aspects</a></li>
-                  <li><a href="/versions/{{ site.version }}/skylark/repository_rules.html">Repository Rules</a></li>
-                  <li><a href="/versions/{{ site.version }}/skylark/faq.html">FAQ</a></li>
+                  <li><a href="/versions/{{ current_version }}/skylark/macros.html">Macros</a></li>
+                  <li><a href="/versions/{{ current_version }}/skylark/rules.html">Rules</a></li>
+                  <li><a href="/versions/{{ current_version }}/skylark/depsets.html">Depsets</a></li>
+                  <li><a href="/versions/{{ current_version }}/skylark/aspects.html">Aspects</a></li>
+                  <li><a href="/versions/{{ current_version }}/skylark/repository_rules.html">Repository Rules</a></li>
+                  <li><a href="/versions/{{ current_version }}/skylark/faq.html">FAQ</a></li>
                 </ul>
               </li>
 
@@ -238,18 +253,18 @@ <h3>Extending Bazel</h3>
                   Best Practices<span class="caret"></span>
                 </a>
                 <ul class="collapse sidebar-nav sidebar-submenu" id="starlark-practices">
-                  <li><a href="/versions/{{ site.version }}/skylark/bzl-style.html">.bzl Style Guide</a></li>
-                  <li><a href="/versions/{{ site.version }}/skylark/testing.html">Testing</a></li>
+                  <li><a href="/versions/{{ current_version }}/skylark/bzl-style.html">.bzl Style Guide</a></li>
+                  <li><a href="/versions/{{ current_version }}/skylark/testing.html">Testing</a></li>
                   <li><a href="https://skydoc.bazel.build" target="_blank">Documenting Rules</a></li>
-                  <li><a href="/versions/{{ site.version }}/skylark/skylint.html">Linter</a></li>
-                  <li><a href="/versions/{{ site.version }}/skylark/performance.html">Optimizing Performance</a></li>
-                  <li><a href="/versions/{{ site.version }}/skylark/deploying.html">Deploying Rules</a></li>
+                  <li><a href="/versions/{{ current_version }}/skylark/skylint.html">Linter</a></li>
+                  <li><a href="/versions/{{ current_version }}/skylark/performance.html">Optimizing Performance</a></li>
+                  <li><a href="/versions/{{ current_version }}/skylark/deploying.html">Deploying Rules</a></li>
                 </ul>
               </li>
 
               <li><a href="https://github.com/bazelbuild/examples/tree/master/rules">Examples</a></li>
-              <li><a href="/versions/{{ site.version }}/skylark/lib/skylark-overview.html">API Reference</a></li>
-              <li><a href="/versions/{{ site.version }}/skylark/language.html">Starlark Language</a></li>
+              <li><a href="/versions/{{ current_version }}/skylark/lib/skylark-overview.html">API Reference</a></li>
+              <li><a href="/versions/{{ current_version }}/skylark/language.html">Starlark Language</a></li>
             </ul>
           </nav>
         </div>
diff --git a/site/_sass/sidebar.scss b/site/_sass/sidebar.scss
index 19879374bdc0bf..e2f5ae2056f284 100644
--- a/site/_sass/sidebar.scss
+++ b/site/_sass/sidebar.scss
@@ -50,6 +50,13 @@ $sidebar-hover-border-color: #66bb6a;
       padding-left: 10px;
     }
   }
+
+  select {
+    padding: 3px 4px;
+    border: 2px solid $sidebar-border-color;
+    border-radius: 3px;
+    overflow: hidden;
+  }
 }
 
 @media (min-width: 992px) {
diff --git a/site/jekyll-tree.sh b/site/jekyll-tree.sh
index fd767ca7eff3d5..1c2f2ab60452be 100755
--- a/site/jekyll-tree.sh
+++ b/site/jekyll-tree.sh
@@ -40,10 +40,7 @@ readonly TMP=$(mktemp -d "${TMPDIR:-/tmp}/tmp.XXXXXXXX")
 readonly OUT_DIR="$TMP/out"
 trap "rm -rf ${TMP}" EXIT
 
-# TODO: Create a variant of this script for cutting versions of documentation
-# for Bazel releases. For that case, consider extracting the Git branch or tag
-# name to be used as the versioned directory name.
-readonly VERSION="master"
+readonly VERSION="${DOC_VERSION:-master}"
 readonly VERSION_DIR="$OUT_DIR/versions/$VERSION"
 
 # Unpacks the base Jekyll tree, Build Encyclopedia, Skylark Library, and


Test patch: