Minor documentation fixes. Make sidebar navigation look more consistent.

--
MOS_MIGRATED_REVID=98934930

6 files changed, 48 insertions, 42 deletions

diff --git a/README.md b/README.md
index d6008ca502..1142b8837a 100644
--- a/README.md
+++ b/README.md
@@ -33,7 +33,7 @@ Find more background about Bazel in our [FAQ](http://bazel.io/faq.html).
   * How to [extend Bazel](http://bazel.io/docs/skylark/index.html)
   * The test environment is described in the [test encyclopedia](http://bazel.io/docs/test-encyclopedia.html)
 
-* About the Bazel project:
+## About the Bazel project:
 
   * How to [contribute to Bazel](http://bazel.io/contributing.html)
   * Our [governance plan](http://bazel.io/governance.html)
diff --git a/site/contributing.md b/site/contributing.md
index d5966a0101..e02b8e873c 100644
--- a/site/contributing.md
+++ b/site/contributing.md
@@ -4,8 +4,8 @@ layout: community
 
 # Contributing to Bazel
 
-We welcome contributions! This page covers setting up your machine to develop
-Bazel and, when you've made a patch, how to submit it.
+<p class="lead">We welcome contributions! This page covers setting up your
+machine to develop Bazel and, when you've made a patch, how to submit it.</p>
 
 ## How can I contribute to Bazel?
 
@@ -23,9 +23,7 @@ a lot of time in a patch.
 <li>Prepare a git commit that implements the feature. Don't forget to add tests.
 <li>Create a new code review on <a href="https://bazel-review.googlesource.com">Gerrit</a>
    by running:
-   <pre>
-$ git push https://bazel.googlesource.com/bazel HEAD:refs/for/master
-   </pre>
+   <pre>$ git push https://bazel.googlesource.com/bazel HEAD:refs/for/master</pre>
    Gerrit upload requires that you:
    <ul>
      <li>Have signed a
@@ -76,7 +74,8 @@ To work with IntelliJ, run `sh scripts/setup-intellij.sh` from the root of the
 source tree and it will create the necessary project files. You can then open
 the folder as a project in IntelliJ.
 
-### Compiling Bazel {#compile-bazel}
+<a name="compile-bazel"></a>
+### Compiling Bazel
 
 To test out bazel, you need to compile it. There is currently two ways of
 compiling it:
@@ -103,10 +102,12 @@ When modifying Bazel, you want to make sure that the following still works:
 
 Start creating a debug configuration for both C++ and Java in your bazelrc with the following:
 
+```
 build:debug -c dbg
 build:debug --javacopt="-g"
 build:debug --copt="-g"
 build:debug --strip="never"
+```
 
 Then you can rebuild Bazel with `bazel build --config debug //src:bazel` and use your favorite
 debugger to start debugging.
diff --git a/site/docs/cpp.md b/site/docs/cpp.md
index 4ce0374e11..8f8900dcda 100644
--- a/site/docs/cpp.md
+++ b/site/docs/cpp.md
@@ -112,8 +112,8 @@ cc_library(
 )
 ```
 
-This expresses that the "sandwich" library depends on the "bread" library,
-which depends on the "flour" library.
+This expresses that the `sandwich` library depends on the `bread` library,
+which depends on the `flour` library.
 
 Adding include paths
 --------------------
@@ -177,7 +177,7 @@ more complicated:
   link errors for duplicate symbols.
 * It uses header files that relative to the `gtest-1.7.0/include/` directory
   (`"gtest/gtest.h"`), so we must add that directory the includes.
-* It uses "private" header files in src/, so we add "." to the includes so it
+* It uses "private" header files in `src/`, so we add `.` to the includes so it
   can `#include "src/gtest-internal-inl.h"`.
 * It needs to link in pthread, so we add that as a `linkopt`.
 
diff --git a/site/docs/external.md b/site/docs/external.md
index 583aaabe87..e11f49fdd9 100644
--- a/site/docs/external.md
+++ b/site/docs/external.md
@@ -10,8 +10,8 @@ impractical for some version control systems and goes against how many existing
 projects are structured. Thus, Bazel has a system for pulling in dependencies
 from outside of the build root.
 
-External dependencies can be specified in a _WORKSPACE_ file in the build root.
-This _WORKSPACE_ file uses the same Python-like syntax of BUILD files, but
+External dependencies can be specified in a `WORKSPACE` file in the build root.
+This `WORKSPACE` file uses the same Python-like syntax of BUILD files, but
 allows a different set of rules. See the full list of rules that are allowed in
 the [Workspace](/docs/build-encyclopedia.html) list of rules in the Build
 Encyclopedia.
@@ -22,24 +22,25 @@ By default, external dependencies are fetched as needed during `bazel build`. If
 you would like to disable this behavior or prefetch dependencies, use
 [`bazel fetch`](http://bazel.io/docs/bazel-user-manual.html#fetch).
 
+<a name="transitive-dependencies"></a>
 ## Transitive dependencies
 
-Bazel only reads dependencies listed in your build root's _WORKSPACE_ file. This
-means that if your project (_A_) depends on another project (_B_) which list a
-dependency on project _C_ in its _WORKSPACE_ file, you'll have to add both _B_
-and _C_ to your project's _WORKSPACE_ file. This can balloon the _WORKSPACE_
-file size, but hopefully limits the chances of having one library include _C_
-at version 1.0 and another include _C_ at 2.0.
+Bazel only reads dependencies listed in your build root's `WORKSPACE` file. This
+means that if your project (`A`) depends on another project (`B`) which list a
+dependency on project `C` in its `WORKSPACE` file, you'll have to add both `B`
+and `C` to your project's `WORKSPACE` file. This can balloon the `WORKSPACE`
+file size, but hopefully limits the chances of having one library include `C`
+at version 1.0 and another include `C` at 2.0.
 
-Bazel provides a tool to help generate these expansive _WORKSPACE_ files, called
+Bazel provides a tool to help generate these expansive `WORKSPACE` files, called
 `generate_workspace`. Run the following to build the tool and see usage:
 
 ```
 bazel run src/main/java/com/google/devtools/build/workspace:generate_workspace
 ```
 
-You can either specify directories containing Bazel projects (i.e., _WORKSPACE_
-files) or Maven projects (i.e., _pom.xml_ files).  For example:
+You can either specify directories containing Bazel projects (i.e., `WORKSPACE`
+files) or Maven projects (i.e., `pom.xml` files).  For example:
 
 ```bash
 $ bazel run src/main/java/com/google/devtools/build/workspace:generate_workspace -- \
@@ -51,17 +52,17 @@ Wrote:
 /tmp/1437415510621-0/2015-07-20-14-05-10.BUILD
 ```
 
-The _WORKSPACE_ file contains the transitive dependencies of given projects. The
-_BUILD_ file contains a single target, `transitive-deps`, that contains all of
+The `WORKSPACE` file contains the transitive dependencies of given projects. The
+`BUILD` file contains a single target, `transitive-deps`, that contains all of
 the dependencies. You can copy these files to your project and add
-`transitive-deps` as a dependency of your `java_` targets in _BUILD_ files.
+`transitive-deps` as a dependency of your `java_` targets in `BUILD` files.
 
 If you specify multiple Bazel or Maven projects, they will all be combined into
-one _WORKSPACE_ file (e.g., if the Bazel project depends on junit and the Maven
+one `WORKSPACE` file (e.g., if the Bazel project depends on junit and the Maven
 project also depends on junit, junit will only appear once as a dependency in
 the output).
 
-You may wish to curate the generated _WORKSPACE_ file to ensure it is using the
+You may wish to curate the generated `WORKSPACE` file to ensure it is using the
 correct version of each dependency. If several different versions of an artifact
 are requested (by different libraries that depend on it), then
 `generate_workspace` chooses a version and annotates the `maven_jar` with the
@@ -82,7 +83,7 @@ maven_jar(
 This indicates that `org.springframework:spring:2.5.6`, `javax.mail:mail:1.4`,
 `httpunit:httpunit:1.6`, `org.springframework:spring-support:2.0.2`, and
 `org.slf4j:nlog4j:1.2.24` all depend on javax.activation. However, two of these
-libraries wanted version 1.1 and three of them wanted 1.0.2. The _WORkSPACE_
+libraries wanted version 1.1 and three of them wanted 1.0.2. The `WORkSPACE`
 file is using version 1.1, but that might not be the right version to use.
 
 You may also want to break `transitive-deps` into smaller targets, as it is
@@ -101,11 +102,11 @@ use
 or [`http_archive`](http://bazel.io/docs/build-encyclopedia.html#http_archive)
 to symlink it from the local filesystem or download it (respectively).
 
-For example, suppose you are working on a project, _my-project/_, and you want
-to depend on targets from your coworker's project, _coworkers-project/_. Both
+For example, suppose you are working on a project, `my-project/`, and you want
+to depend on targets from your coworker's project, `coworkers-project/`. Both
 projects use Bazel, so you can add your coworker's project as an external
 dependency and then use any targets your coworker has defined from your own
-BUILD files. You would add the following to _my\_project/WORKSPACE_:
+BUILD files. You would add the following to `my\_project/WORKSPACE`:
 
 ```python
 local_repository(
@@ -124,10 +125,10 @@ Rules prefixed with `new_` (e.g.,
 and [`new_http_archive`](http://bazel.io/docs/build-encyclopedia.html#new_http_archive)
 allow you to create targets from projects that do not use Bazel.
 
-For example, suppose you are working on a project, _my-project/_, and you want
-to depend on your coworker's project, _coworkers-project/_. Your coworker's
+For example, suppose you are working on a project, `my-project/`, and you want
+to depend on your coworker's project, `coworkers-project/`. Your coworker's
 project uses `make` to build, but you'd like to depend on one of the .so files
-it generates. To do so, add the following to _my\_project/WORKSPACE_:
+it generates. To do so, add the following to `my_project/WORKSPACE`:
 
 ```python
 new_local_repository(
@@ -154,18 +155,18 @@ files.
 # Caching of external dependencies
 
 Bazel caches external dependencies and only re-downloads or updates them when
-the _WORKSPACE_ file changes. If the _WORKSPACE_ file does not change, Bazel
+the `WORKSPACE` file changes. If the `WORKSPACE` file does not change, Bazel
 assumes that the external dependencies have not changed, either. This can cause
 unexpected results, especially with local repositories.
 
-For instance, in the example above, suppose that _my-project/_ has a target that
+For instance, in the example above, suppose that `my-project/` has a target that
 depends on `@coworkers-project//:a`, which you build. Then you change to
-_coworkers-project/_ and pull the latest updates to their library, which changes
-the behavior of `@coworkers-project//:a`. If you go back to _my-project/_ and
+`coworkers-project/` and pull the latest updates to their library, which changes
+the behavior of `@coworkers-project//:a`. If you go back to `my-project/` and
 build your target again, it will assume `@coworkers-project//:a` is already
 up-to-date and reuse the cached library (instead of realizing that the sources
 have changed and, thus, rebuilding).
 
 To avoid this situation, prefer remote repositories to local ones and do not
-manually change the files in _\[output\_base\]/external_. If you change a file
-in _\[output\_base\]/external_, rerun `bazel fetch ...` to update the cache.
+manually change the files in `[output_base]/external`. If you change a file
+in `[output_base]/external`, rerun `bazel fetch ...` to update the cache.
diff --git a/site/docs/skylark/rules.md b/site/docs/skylark/rules.md
index b3204fa4af..8338e6e69e 100644
--- a/site/docs/skylark/rules.md
+++ b/site/docs/skylark/rules.md
@@ -111,7 +111,8 @@ my_rule = rule(
 )
 ```
 
-Output files  {#output-files}
+<a name="output-files"></a>
+Output files
 ------------
 
 A target can declare output files, which must be generated by the target's
diff --git a/site/governance.md b/site/governance.md
index 548952ad7a..c94b110ff7 100644
--- a/site/governance.md
+++ b/site/governance.md
@@ -53,7 +53,7 @@ list), but this will hopefully change over time.
     extension points if they do not run counter to the internal requirements of any of the core
     contributors.
 
-## Are you done open sourcing Bazel? {#isbazelopen}
+## Are you done open sourcing Bazel?
 
 Open sourcing Bazel is a work-in-progress. In particular, we're still working on open sourcing:
 
@@ -75,7 +75,10 @@ not available on GitHub and probably never will be.
 
 ### Core Contributors
 
-__Contact the core team at bazel-discuss@googlegroups.com.__
+<p class="lead">
+Contact the core team at <a href="mailto:bazel-dev@googlegroups.com">
+bazel-dev@googlegroups.com</a>.
+</p>
 
 The current group is: