Standardize install pages
- Standardized steps to "Part X: " form
- Shortened some redundant titles
- Made header sizes consistent
Tested with styling changes from https://github.com/bazelbuild/bazel/pull/10762. In particular:
formatted changes for the new right-side page navbar.
Serves https://github.com/bazelbuild/bazel/issues/10794 (but
since these are versioned these will release on a different
timeline than styling changes)
Closes #10817.
PiperOrigin-RevId: 296272232
diff --git a/site/docs/completion.md b/site/docs/completion.md
index 3968fc8..a5129d7 100644
--- a/site/docs/completion.md
+++ b/site/docs/completion.md
@@ -9,7 +9,7 @@
and Zsh. This lets you tab-complete command names, flags names and flag values,
and target names.
-<h2 id="bash">Bash completion</h2>
+<h2 id="bash">Bash</h2>
Bazel comes with a Bash completion script.
@@ -65,7 +65,7 @@
source /path/to/bazel-complete.bash
```
-<h2 id="zsh">Zsh completion</h2>
+<h2 id="zsh">Zsh</h2>
Bazel also comes with a Zsh completion script. To install it:
diff --git a/site/docs/install-compile-source.md b/site/docs/install-compile-source.md
index 8359b20..99debcb 100644
--- a/site/docs/install-compile-source.md
+++ b/site/docs/install-compile-source.md
@@ -38,7 +38,7 @@
Detailed instructions follow below.
-<h3 id="build-bazel-install-bazel">1. Get the latest Bazel release</h3>
+<h3 id="build-bazel-install-bazel">Step 1: Get the latest Bazel release</h3>
**Goal**: Install or download a release version of Bazel. Make sure you can run
it by typing `bazel` in a terminal.
@@ -67,7 +67,7 @@
You must make the binary executable by running `chmod +x /path/to/bazel`.
-<h3 id="build-bazel-git">2. Download Bazel's sources from GitHub</h3>
+<h3 id="build-bazel-git">Step 2: Download Bazel's sources from GitHub</h3>
If you are familiar with Git, then just git clone https://github.com/bazelbuild/bazel
@@ -81,13 +81,14 @@
For example create a `bazel-src` directory under your home directory and
extract there.
-<h3 id="build-bazel-prerequisites">3. Install prerequisites</h3>
+<h3 id="build-bazel-prerequisites">Step 3: Install prerequisites</h3>
Install the same prerequisites as for bootstrapping (see below) -- JDK, C++
compiler, MSYS2 (if you are building on Windows), etc.
-<h3 id="build-bazel-on-unixes">4. Build Bazel on Ubuntu Linux, macOS, and other
-Unix-like systems</h3>
+<h3 id="build-bazel-on-unixes">Step 4: Build Bazel</h3>
+
+<h4 id="build-bazel-on-unixes">Ubuntu Linux, macOS, and other Unix-like systems</h4>
([Scroll down](#build-bazel-on-windows) for instructions for Windows.)
@@ -112,7 +113,7 @@
4. The output will be at `bazel-bin/src/bazel-dev` (or `bazel-bin/src/bazel`).
-<h3 id="build-bazel-on-windows">4. Build Bazel on Windows</h3>
+<h4 id="build-bazel-on-windows">Windows</h4>
([Scroll up](#build-bazel-on-unixes) for instructions for Linux, macOS, and other
Unix-like systems.)
@@ -140,7 +141,7 @@
4. The output will be at `bazel-bin\src\bazel-dev.exe` (or
`bazel-bin\src\bazel.exe`).
-<h3 id="build-bazel-install">5. Install the built binary</h3>
+<h3 id="build-bazel-install">Step 5: Install the built binary</h3>
Actually, there's nothing to install.
@@ -154,7 +155,7 @@
You can also build Bazel from scratch, without using an existing Bazel binary.
-<h3 id="download-distfile">1. Download Bazel's sources (distribution archive)</h3>
+<h3 id="download-distfile">Step 1: Download Bazel's sources (distribution archive)</h3>
(This step is the same for all platforms.)
@@ -177,7 +178,7 @@
We recommend to also verify the signature made by our
[release key](https://bazel.build/bazel-release.pub.gpg) 3D5919B448457EE0.
-<h3 id="bootstrap-unix">2. Bootstrap Bazel on Ubuntu Linux, macOS, and other Unix-like systems</h3>
+<h3 id="bootstrap-unix">Step 2a: Bootstrap Bazel on Ubuntu Linux, macOS, and other Unix-like systems</h3>
([Scroll down](#bootstrap-windows) for instructions for Windows.)
@@ -219,7 +220,7 @@
[`SOURCE_DATE_EPOCH`](https://reproducible-builds.org/specs/source-date-epoch/)
in the "Run the compilation script" step.
-<h3 id="bootstrap-windows">2. Bootstrap Bazel on Windows</h3>
+<h3 id="bootstrap-windows">Step 2b: Bootstrap Bazel on Windows</h3>
([Scroll up](#bootstrap-unix) for instructions for Linux, macOS, and other
Unix-like systems.)
diff --git a/site/docs/install-redhat.md b/site/docs/install-redhat.md
index 09b3d0e..6d7d046 100644
--- a/site/docs/install-redhat.md
+++ b/site/docs/install-redhat.md
@@ -12,7 +12,7 @@
The commands below must be run either via `sudo` or while logged in as `root`.
-## Installing Bazel on Fedora 25+
+## Installing on Fedora 25+
1. The [DNF](https://fedoraproject.org/wiki/DNF) package manager can install
Bazel from the [COPR](https://copr.fedorainfracloud.org/) repository. Install
@@ -30,7 +30,7 @@
dnf install bazel
```
-## Installing Bazel on CentOS 7
+## Installing on CentOS 7
1. Download the corresponding `.repo` file from
[Fedora COPR](https://copr.fedorainfracloud.org/coprs/vbatts/bazel/repo/epel-7/vbatts-bazel-epel-7.repo)
diff --git a/site/docs/install-windows.md b/site/docs/install-windows.md
index 550cd1c..39a9635 100644
--- a/site/docs/install-windows.md
+++ b/site/docs/install-windows.md
@@ -5,7 +5,9 @@
# Installing Bazel on Windows
-## 1. Check your system
+## Installing
+
+### Step 1: Check your system
Recommended: 64 bit Windows 10, version 1703 (Creators Update) or newer, enable "Developer Mode".
@@ -20,11 +22,11 @@
* Older Windows 10 versions, disabled "Developer Mode" (enabling the mode just lets you use the
`--enable_runfiles` Bazel flag)
-## 2. Install the prerequisites
+### Step 2: Install the prerequisites
* [Visual C++ Redistributable for Visual Studio 2015](https://www.microsoft.com/en-us/download/details.aspx?id=48145)
-## 3. Download Bazel
+### Step 3: Download Bazel
[Download the Bazel binary (<code>bazel-<version>-windows-x86_64.exe</code>) from
GitHub](https://github.com/bazelbuild/bazel/releases).
@@ -35,11 +37,11 @@
* [Download Bazelisk](https://github.com/bazelbuild/bazelisk) instead of Bazel. Bazelisk is a
Bazel launcher that ensures you always use the latest Bazel release.
-* [Install Bazel from Chocolatey](#install-using-chocolatey) (see below)
-* [Install Bazel from Scoop](#install-using-scoop) (see below)
+* [Install Bazel from Chocolatey](#using-chocolatey)
+* [Install Bazel from Scoop](#using-scoop)
* [Build Bazel from source](install-compile-source.html)
-## 4. Optional: configure output directories
+### Step 4 (optional): Configure output directories
**You can skip this step. Bazel can work without configuring the output directories, and will use
its default values.**
@@ -68,7 +70,7 @@
You can tell Bazel not to create these junctions with `--symlink_prefix=/`.
-## 5. Optional: install compilers and language runtimes
+### Step 5 (optional): Install compilers and language runtimes
**You can skip this step. Bazel can work without these programs, but you may need them.**
@@ -118,32 +120,20 @@
Also supported: Python 3 or newer for Windows x86-64
-## 5. Done
+### Step 6: Done
**You have successfully installed Bazel.**
-Troubleshooting: see the "Appendix" > "Troubleshooting" section below.
+Troubleshooting: see [troubleshooting](#troubleshooting) below.
-Tutorials: see the "Tutorials" section on the left navigation panel.
+Tutorials: see [Getting Started with Bazel](getting-started.html) >
+[Tutorials](getting-started.html#tutorials).
---
-# Appendix
-
-Table of contents:
-
-* [Troubleshooting](#troubleshooting)
- * [Problem: Bazel does not find Bash or bash.exe](#problem-bazel-does-not-find-bash-or-bashexe)
- * [Problem: Bazel does not find Visual Studio or Visual C++](#problem-bazel-does-not-find-visual-studio-or-visual-c)
-
-* [Other ways to install Bazel](#other-ways-to-install-bazel)
- * [Install from Chocolatey](#install-using-chocolatey)
- * [Install from Scoop](#install-using-scoop)
- * [Build from source](install-compile-source.html)
-
## Troubleshooting
-### Problem: Bazel does not find Bash or bash.exe
+### Bazel does not find Bash or bash.exe
**Possible reasons**:
@@ -182,7 +172,7 @@
If you open a new cmd.exe or PowerShell terminal and run Bazel now, it will find Bash.
-### Problem: Bazel does not find Visual Studio or Visual C++
+### Bazel does not find Visual Studio or Visual C++
**Possible reasons**:
@@ -222,7 +212,7 @@
## Other ways to install Bazel
-### Install using Chocolatey
+### Using Chocolatey
1. Install the [Chocolatey](https://chocolatey.org) package manager
@@ -238,7 +228,7 @@
guide](https://bazel.build/windows-chocolatey-maintenance.html) for more
information about the Chocolatey package.
-### Install using Scoop
+### Using Scoop
1. Install the [Scoop](https://scoop.sh/) package manager using the following PowerShell command:
@@ -251,3 +241,7 @@
See [Scoop installation and package maintenance
guide](https://bazel.build/windows-scoop-maintenance.html) for more
information about the Scoop package.
+
+### Build from source
+
+See [here](install-compile-source.html).
\ No newline at end of file
