I know nothing about zsh.

@schroederc : I believe you added the zsh completion script to Bazel in commit https://github.com/bazelbuild/bazel/commit/6b2766dd0, so I'm hoping you can help.
@damienmg : you approved Cody's change, you may know about zsh. also confused by this sentence The `_bazel` file just needs to be in one of the directories listed in your `fpath`.  The installation example shows how add a directory to your `fpath` and move the `_bazel` file into it, but if you already have a directory in your `fpath` that you prefer, you can move `_bazel` there instead.

It doesn't matter what the name of the directory is at all (`$HOME/.zsh/completion/` is just commonly used).  The `_bazel` filename only matters because that is what the completion function is named (i.e. https://github.com/bazelbuild/bazel/blob/64d9a4d6dcd720a3b7a60ff550a17a7707dd41d0/scripts/zsh_completion/_bazel#L247).  Otherwise, it's only a convention to name the completion file/function after the command it completes with a leading underscore.  When `compinit` is run, zsh will look through all files in all of the `fpath` directories and look for `#compdef` lines at the start of each to register completion functions. Oh, I see. So the documentation was written from the perspective of that file and was copy/pasted/generated into documentation here: https://docs.bazel.build/versions/master/install.html#zsh

It looks like there may be a need to reword it. The document disappeared. Is zsh auto completion not supported anymore? Looking at the [history of install.md](https://github.com/bazelbuild/bazel/commits/master/site/docs/install.md), the instructions were there at [3e0c545404be6bce908d035044a5ff0ee41cc472](https://github.com/bazelbuild/bazel/blob/3e0c545404be6bce908d035044a5ff0ee41cc472/site/docs/install.md), but not anymore at [70e84f8926bd2cc38fea9e74af292d19038607b8](https://github.com/bazelbuild/bazel/blob/70e84f8926bd2cc38fea9e74af292d19038607b8/site/docs/install.md).

Let me see if they are still up-to-date and put them back. FYI: alternatively, you guys may try this https://github.com/jackwish/bazel which is to make the process easier. on macOS the zsh completions are installed automatically if you install via homebrew
Can someone elaborate on the instructions to install zsh completion?
I'm looking at the instructions for how to install zsh completion [here](https://docs.bazel.build/versions/master/install.html#zsh) and am left a little confused about what to do. I'm only a casual user of ZSH, so I think I'm missing something fundamental.

># Getting zsh completion
>
>Bazel also comes with a zsh completion script. To install it:
>
>Add this script to a directory on your `$fpath`:
>```
>fpath[1,0]=~/.zsh/completion/
>mkdir -p ~/.zsh/completion/
>cp scripts/zsh_completion/_bazel ~/.zsh/completion
>```
>
>You may have to call `rm -f ~/.zcompdump; compinit` the first time to make it work.
>
>Optionally, add the following to your .zshrc.
>```
># This way the completion script does not have to parse Bazel's options
># repeatedly.  The directory in cache-path must be created manually.
>zstyle ':completion:*' use-cache on
>zstyle ':completion:*' cache-path ~/.zsh/cache
>```

The second step is very clear, but the first is confusing to me.

My `$fpath` includes a whole list of directories. So should I just pick a directory and write a file with the contents of that first script? Does it matter what I name it? Is there an existing convention I should be following? I'm reviewing the docs for zsh functions at http://zsh.sourceforge.net/Doc/Release/Functions.html, but I'm still unsure of how to proceed.
site/_layouts/documentation.html site/docs/install-os-x.md site/docs/install-ubuntu.md
site/_layouts/documentation.html site/docs/completion.md site/docs/install-os-x.md site/docs/install-ubuntu.md
diff --git a/site/_layouts/documentation.html b/site/_layouts/documentation.html
index 04b2fd401b1ea1..77410c6b11d506 100644
--- a/site/_layouts/documentation.html
+++ b/site/_layouts/documentation.html
@@ -47,6 +47,7 @@ <h3>Using Bazel</h3>
                    <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>
                  </ul>
                 </li>
diff --git a/site/docs/completion.md b/site/docs/completion.md
new file mode 100644
index 00000000000000..4936bf6aaa8713
--- /dev/null
+++ b/site/docs/completion.md
@@ -0,0 +1,90 @@
+---
+layout: documentation
+title: "Command-Line Completion"
+---
+
+# Command-Line Completion
+
+You can enable command-line completion (also known as tab-completion) in Bash
+and Zsh. This lets you tab-complete command names, flags names and flag values,
+and target names.
+
+<h2 id="bash">Bash completion</h2>
+
+Bazel comes with a Bash completion script.
+
+If you installed Bazel:
+
+*   From the APT repository, then you're done -- the Bash completion script is
+    already installed in `/etc/bash_completion.d`.
+
+*   From the installer downloaded from GitHub, then:
+    1.  Locate the absolute path of the completion file. The installer copied it
+        to the `bin` directory.  
+
+        Example: if you ran the installer with `--user`, this will be
+        `$HOME/.bazel/bin`. If you ran the installer as root, this will be
+        `/usr/local/bazel/bin`.
+    2.  Do one of the following:
+        *   Either copy this file to your completion directory (if you have
+            one).
+
+            Example: on Ubuntu this is the `/etc/bash_completion.d` directory.
+        *   Or source the completion file from Bash's RC file.
+
+            Add a line similar to the one below to your `~/.bashrc` (on Ubuntu)
+            or `~/.bash_profile` (on macOS), using the path to your completion
+            file's absolute path:
+
+            ```
+            source /path/to/bazel-complete.bash
+            ```
+
+*   Via [bootstrapping](install-compile-source.html), then:
+    1.  Build the completion script:
+
+        ```
+        bazel build //scripts:bazel-complete.bash
+        ```
+    2.  The completion file is built under
+        `bazel-bin/scripts/bazel-complete.bash`.
+
+        Do one of the following:
+        *   Either copy this file to your completion directory (if you have
+            one).
+
+            Example: on Ubuntu this is the `/etc/bash_completion.d` directory
+        *   Or copy it somewhere on your local disk, e.g. to `$HOME`, and
+            source the completion file from Bash's RC file.
+
+            Add a line similar to the one below to your `~/.bashrc` (on Ubuntu)
+            or `~/.bash_profile` (on macOS), using the path to your completion
+            file's absolute path:
+
+            ```
+            source /path/to/bazel-complete.bash
+            ```
+
+<h2 name="zsh">Zsh completion</h2>
+
+Bazel also comes with a Zsh completion script. To install it:
+
+1.  Add this script to a directory on your `$fpath`:
+
+    ```
+    fpath[1,0]=~/.zsh/completion/
+    mkdir -p ~/.zsh/completion/
+    cp scripts/zsh_completion/_bazel ~/.zsh/completion
+    ```
+
+    You may have to call `rm -f ~/.zcompdump; compinit`
+    the first time to make it work.
+
+2.  Optionally, add the following to your .zshrc.
+
+    ```
+    # This way the completion script does not have to parse Bazel's options
+    # repeatedly.  The directory in cache-path must be created manually.
+    zstyle ':completion:*' use-cache on
+    zstyle ':completion:*' cache-path ~/.zsh/cache
+    ```
diff --git a/site/docs/install-os-x.md b/site/docs/install-os-x.md
index eb8a5aced14465..77f2f7d4e5ab0e 100644
--- a/site/docs/install-os-x.md
+++ b/site/docs/install-os-x.md
@@ -13,8 +13,8 @@ Install Bazel on macOS using one of the following methods:
 
 Bazel comes with two completion scripts. After installing Bazel, you can:
 
-*   Access the [bash completion script](install.md)
-*   Install the [zsh completion script](install.md)
+*   Access the [bash completion script](completion.md#bash)
+*   Install the [zsh completion script](completion.md#zsh)
 
 ## <a name="install-with-installer-mac-os-x"></a>Installing using binary installer
 
diff --git a/site/docs/install-ubuntu.md b/site/docs/install-ubuntu.md
index ba36e6d3a4b6b3..a52ae8b39165ad 100644
--- a/site/docs/install-ubuntu.md
+++ b/site/docs/install-ubuntu.md
@@ -18,8 +18,8 @@ Install Bazel on Ubuntu using one of the following methods:
 
 Bazel comes with two completion scripts. After installing Bazel, you can:
 
-*   Access the [bash completion script](install.md)
-*   Install the [zsh completion script](install.md)
+*   Access the [bash completion script](completion.md#bash)
+*   Install the [zsh completion script](completion.md#zsh)
 
 ## <a name="install-with-installer-ubuntu"></a>Installing using binary installer
 
