diff --git a/site/docs/backward-compatibility.md b/site/docs/backward-compatibility.md
index 500f1a0..a3df992 100644
--- a/site/docs/backward-compatibility.md
+++ b/site/docs/backward-compatibility.md
@@ -26,9 +26,9 @@
 1. APIs and behavior guarded by an `--experimental_*` flag can change at any time.
 1. Users should never run their production builds with `--experimental_*`  or `--incompatible_*` flags.
 
-### How to follow this policy
+## How to follow this policy
 
-* [For Bazel Users - how to update
+* [For Bazel users - how to update
   Bazel](updating-bazel.html)
 * [For contributors - best practices for incompatible changes](https://bazel.build/breaking-changes-guide.html)
 * <a href='https://github.com/bazelbuild/continuous-integration/tree/master/docs/release-playbook.%6D%64'>For release managers - how to update issue labels and release</a>
diff --git a/site/docs/configurable-attributes.md b/site/docs/configurable-attributes.md
index 2c74ca8..4ecf439 100644
--- a/site/docs/configurable-attributes.md
+++ b/site/docs/configurable-attributes.md
@@ -90,6 +90,7 @@
     <td><code>[":generic_lib"]</code></td>
   </tr>
 </table>
+
 `select()` serves as a placeholder for a value that will be chosen based on
 *configuration conditions*. These conditions are labels that refer to
 [`config_setting`](be/general.html#config_setting) targets. By using `select()`
@@ -733,7 +734,7 @@
 
 ## FAQ
 
-## <a name="macros-select"></a>Why doesn't select() work in macros?
+### <a name="macros-select"></a>Why doesn't select() work in macros?
 select() *does* work in rules! See [Rules compatibility](#rules) for
 details.
 
@@ -844,7 +845,7 @@
 DEBUG: /myworkspace/myproject/defs.bzl:15:3: My name is sad_macro_less_sad with custom message: FIRST STRING.
 ```
 
-## <a name="boolean-select"></a>Why does select() always return true?
+### <a name="boolean-select"></a>Why does select() always return true?
 Because *macros* (but not rules) by definition
 [can't evaluate select(s)](#macros-select), any attempt to do so
 usually produces an error:
@@ -888,7 +889,7 @@
 [Pythonic](https://docs.python.org/release/2.5.2/lib/truth.html) design
 standards, all objects aside from a very small number of exceptions
 automatically return true.
-## <a name="inspectable-select"></a>Can I read select() like a dict?
+### <a name="inspectable-select"></a>Can I read select() like a dict?
 Fine. Macros [can't](#macros-select) evaluate select(s) because
 macros are evaluated before Bazel knows what the command line flags are.
 
@@ -946,7 +947,7 @@
     )
 ```
 
-## <a name="bind-select"></a>Why doesn't select() work with bind()?
+### <a name="bind-select"></a>Why doesn't select() work with bind()?
 
 Because [`bind()`](be/workspace.html#bind) is a WORKSPACE rule, not a BUILD rule.
 
diff --git a/site/docs/test-encyclopedia.html b/site/docs/test-encyclopedia.html
index cde88be..2536fa5 100644
--- a/site/docs/test-encyclopedia.html
+++ b/site/docs/test-encyclopedia.html
@@ -41,7 +41,7 @@
 specification takes precedence.</p>
 
 
-<h3>Purpose of Tests</h3>
+<h2>Purpose of Tests</h2>
 
 <p>The purpose of Bazel tests is to confirm some property of the source files
 checked into the repository.  (In this document, "source files" includes test data,
@@ -62,7 +62,7 @@
 <p>Currently, such behavior is not enforced. However, test runners reserve the
 right to add such enforcement in the future.</p>
 
-<h3>Role of the Build System</h3>
+<h2>Role of the Build System</h2>
 
 <p>Test rules are analogous to binary rules in that each must yield an
 executable program.  For some languages, this is a stub program which combines
@@ -79,7 +79,7 @@
 image provided by the test runner, rather than hardcoded references to absolute
 locations in the source or output tree.</p>
 
-<h3>Role of the Test Runner</h3>
+<h2>Role of the Test Runner</h2>
 
 <p>From the point of view of the test runner, each test is a program which can
 be invoked with <code>execve()</code>.  There may be other ways to execute
@@ -193,7 +193,7 @@
 <p>When executing a test, the test runner must establish certain initial
 conditions.</p>
 
-<h3>Initial Conditions</h3>
+<h2>Initial Conditions</h2>
 
 <p>The test runner must invoke each test with the path to the test
 executable in <code>argv[0]</code>.  This path must be relative and
@@ -310,7 +310,7 @@
 
 <p>The initial scheduling policy and priority are unspecified.</p>
 
-<h3>Role of the Host System</h3>
+<h2>Role of the Host System</h2>
 
 <p>In addition to the aspects of user context under direct control of the
 test runner, the operating system on which tests execute must satisfy certain
@@ -380,7 +380,7 @@
 <p>X Windows may or may not be available. Tests that need an X server should
 start Xvfb.</p>
 
-<h3>Test interaction with the filesystem</h3>
+<h2>Test interaction with the filesystem</h2>
 <p>All file paths specified in test environment variables point to
 somewhere on the local filesystem, unless otherwise specified.</p>
 
@@ -423,7 +423,7 @@
 Bazel sees the file when the test finishes, it will assume that the test exited
 prematurely and mark it as having failed.</p>
 
-<h3 id="tag-conventions">Tag conventions</h3>
+<h2 id="tag-conventions">Tag conventions</h2>
 
 <p>
   Some tags in the test rules have a special
@@ -478,7 +478,7 @@
 </table>
 
 *Note: bazel <code>query</code> does not respect the manual tag.
-<h3>Runfiles</h3>
+<h2>Runfiles</h2>
 
 <p>In the following, assume there is a *_binary() rule labeled <code>//foo/bar:unittest</code>,
 with a run-time dependency on the rule labeled <code>//deps/server:server</code>.</p>
diff --git a/site/docs/updating-bazel.md b/site/docs/updating-bazel.md
index 4e1e637..3c41ef8 100644
--- a/site/docs/updating-bazel.md
+++ b/site/docs/updating-bazel.md
@@ -5,33 +5,56 @@
 
 # Updating Bazel
 
-Bazel defined a [backwards compatibility policy](https://docs.bazel.build/versions/master/backward-compatibility.html)
-(see [guidance for rolling out incompatible changes](https://www.bazel.build/breaking-changes-guide.html) if you are the author of one).
-This page summarized best practices on how to test and migrate your project with upcoming incompatible
-changes and how to provide feedback to the incompatible change authors.
+The Bazel project has a [backwards compatibility
+policy](https://docs.bazel.build/versions/master/backward-compatibility.html)
+(see [guidance for rolling out incompatible
+changes](https://www.bazel.build/breaking-changes-guide.html) if you are the
+author of one). That page summarizes best practices on how to test and migrate
+your project with upcoming incompatible changes and how to provide feedback to
+the incompatible change authors.
 
+## Managing Bazel versions with Bazelisk
+
+The Bazel team implemented a Bazel wrapper called
+[bazelisk](https://github.com/bazelbuild/bazelisk) that helps you manage Bazel
+versions.
+
+Bazelisk can:
+*   Auto-update Bazel to the latest version
+*   Build the project with a Bazel version specified in the .bazelversion
+    file. Check in that file into your version control to ensure reproducibility
+    of your builds.
+*   Help migrate your project for incompatible changes (see above)
+*   Easily try release candidates
 
 ## Recommended migration process
 
-Bazel backwards compatibility policy is designed to avoid _upgrade cliffs_:
-any project can be prepared for the next Bazel release without breaking compatibility with the current release.
+Bazel backwards compatibility policy is designed to avoid _upgrade cliffs_: any
+project can be prepared for the next Bazel release without breaking
+compatibility with the current release.
 
 We recommend the following process for project migration:
 
 
-1. Assume that your project already works with a given Bazel release, say 0.26, and you want to prepare
-   for the next release, say 0.27
+1. Assume that your project already works with a given Bazel release, say 0.26,
+   and you want to prepare for the next release, say 0.27
 2. Find all incompatible changes for which the migration can be started: they are marked with
-   "migration-\<release\>" label on GitHub, for example "[migration-0.26](https://github.com/bazelbuild/bazel/issues?utf8=%E2%9C%93&q=label%3Amigration-0.26+)".
-3. Each of those issues has an associated `--incompatible_*` flag. For each of them, build your project
-   with that flag enabled, and if the build is unsuccessful, fix the project according to
-   [migration recipe](https://docs.bazel.build/versions/master/backward-compatibility.html#incompatible-changes-and-migration-recipes) as specified in the corresponding GitHub issue:
+   "migration-\<release\>" label on GitHub, for example
+   "[migration-0.26](https://github.com/bazelbuild/bazel/issues?utf8=%E2%9C%93&q=label%3Amigration-0.26+)".
+3. Each of those issues has an associated `--incompatible_*` flag. For each of
+   them, build your project with that flag enabled, and if the build is
+   unsuccessful, fix the project according to [migration
+   recipe](https://docs.bazel.build/versions/master/backward-compatibility.html#incompatible-changes-and-migration-recipes)
+   as specified in the corresponding GitHub issue:
     *   Migration guidance is available in the associated GitHub issue.
     *   Migration is always possible in such a way that the project continues to build with and without the flag.
-    *   For some of the incompatible changes migration tooling is available, for example as part of [buildifier](https://github.com/bazelbuild/buildtools/releases). Be sure to check the GitHub issue for migration instructions.
+    *   For some of the incompatible changes migration tooling is available, for
+        example as part of
+        [buildifier](https://github.com/bazelbuild/buildtools/releases). Be sure
+        to check the GitHub issue for migration instructions.
     *   Please report any migration problems by commenting associated GitHub issue.
-4. After all changes are migrated, you can continue to build your project without any flags:
-   it will be ready for the next Bazel release.
+4. After all changes are migrated, you can continue to build your project
+   without any flags: it will be ready for the next Bazel release.
 
 
 ### Migrating with Bazelisk
@@ -39,17 +62,7 @@
 [Bazelisk](https://github.com/bazelbuild/bazelisk) can
 greatly simplify the migration process described above.
 
-*   `bazelisk --strict` will build given targets with all incompatible flags for changes with appropriate migration-* labels.
-*   `bazelisk --migrate` will do even more: it will try every flag and report those for which the build was unsuccessful
-
-
-## Managing Bazel versions with Bazelisk
-
-Bazel team implemented a Bazel wrapper called [bazelisk](https://github.com/bazelbuild/bazelisk) that helps you
-manage Bazel versions.
-
-Bazelisk can:
-*   Autoupdate Bazel to the latest version
-*   Build the project with a Bazel version specified in the .bazelversion file. Check in that file into your version control to ensure reproducibility of your builds.
-*   Help migrate your project for incompatible changes (see above)
-*   Easily try release candidates
+*   `bazelisk --strict` will build given targets with all incompatible flags for
+     changes with appropriate migration-* labels.
+*   `bazelisk --migrate` will do even more: it will try every flag and report
+     those for which the build was unsuccessful