Merge pull request RobotLocomotion#14658 from EricCousineau-TRI/issue…

…-14575-breakoff-pr3

doc: Move Jekyll Markdown pages to `_pages`, hoist headings

doc/bazel.md → doc/_pages/bazel.md

@@ -8,20 +8,20 @@ Drake's primary build system is Bazel.  For more information about Bazel, see
 Drake also offers a CMake build system wrapper that invokes Bazel under the
 hood.
 
-#### Bazel Installation
+# Bazel Installation
 
 Follow Drake's
 [platform-specific setup instructions](/from_source.html#mandatory-platform-specific-instructions)
 to install Bazel.
 
-#### Drake clone and platform setup
+# Drake clone and platform setup
 
 * Start with a **git clone** of drake, per the [Getting Drake](/from_source.html#getting-drake)
   instructions.
 * Continue with the *"Mandatory platform specific instructions"* on the same
   page.
 
-#### Developing Drake using Bazel
+# Developing Drake using Bazel
 
 To build or test Drake, run **bazel build** or **bazel test** with the desired
 target label (and optional configuration options if desired).  We give some
@@ -101,7 +101,7 @@ bazel test --config lint //...                       # Only run style checks; do
   prerequisite libraries are also compiled and linked in ``dbg`` mode.
 * For the definitions of the "``--config``" options see ``drake/tools/bazel.rc``.
 
-##### Running with Flags
+## Running with Flags
 
 In general, to figure out what binary-specific arguments are available, add
 "``-- --help``" to your ``bazel run`` command. If the binary can only run via
@@ -122,7 +122,7 @@ If a Python unittest is run via ``drake_py_unittest_main.py`` (e.g. using
 bazel run bindings/pydrake:py/symbolic_test -- --trace=user --deprecation_action=error
 ```
 
-##### Debugging on macOS
+## Debugging on macOS
 
 On macOS, DWARF debug symbols are emitted to a ``.dSYM`` file.  The Bazel
 ``cc_binary`` and ``cc_test`` rules do not natively generate or expose this
@@ -137,7 +137,7 @@ lldb ./bazel-bin/path/to/my/binary_or_test
 
 For more information, see [https://github.com/bazelbuild/bazel/issues/2537](https://github.com/bazelbuild/bazel/issues/2537).
 
-#### Updating BUILD files
+# Updating BUILD files
 
 Please use the "``buildifier``" tool to format edits to ``BUILD`` files (in the
 same spirit as ``clang-format`` formatting C++ code):
@@ -156,17 +156,17 @@ cd /path/to/drake
 bazel build //tools/lint:buildifier
 ```
 
-#### Proprietary Solvers
+# Proprietary Solvers
 
 The Drake Bazel build currently supports the following proprietary solvers:
 
 * Gurobi 9.0.2
 * MOSEK 9.2
 * SNOPT 7.4
 
-##### Gurobi 9.0.2
+## Gurobi 9.0.2
 
-###### Install on Ubuntu
+### Install on Ubuntu
 
 1. Register for an account on [https://www.gurobi.com](https://www.gurobi.com).
 2. Set up your Gurobi license file in accordance with Gurobi documentation.
@@ -175,7 +175,7 @@ The Drake Bazel build currently supports the following proprietary solvers:
 5. Unzip it.  We suggest that you use ``/opt/gurobi902`` to simplify working with Drake installations.
 6. If you unzipped into a location other than ``/opt/gurobi902``, then call ``export GUROBI_HOME=GUROBI_UNZIP_PATH/linux64`` to set the path you used, where in ``GUROBI_HOME`` folder you can find ``bin`` folder.
 
-###### Install on macOS
+### Install on macOS
 
 1. Register for an account on [http://www.gurobi.com](http://www.gurobi.com).
 2. Set up your Gurobi license file in accordance with Gurobi documentation.
@@ -191,7 +191,7 @@ these tests.  If you will be developing with Gurobi regularly, you may wish
 to specify a more convenient ``--test_tag_filters`` in a local ``.bazelrc``.
 See [https://docs.bazel.build/versions/master/user-manual.html#bazelrc](https://docs.bazel.build/versions/master/user-manual.html#bazelrc).
 
-##### MOSEK
+## MOSEK
 
 The Drake Bazel build system downloads MOSEK 9.2.33 automatically.  No manual
 installation is required.  Set the location of your license file as follows:
@@ -207,13 +207,13 @@ these tests.  If you will be developing with MOSEK regularly, you may wish
 to specify a more convenient ``--test_tag_filters`` in a local ``.bazelrc``.
 See [https://docs.bazel.build/versions/master/user-manual.html#bazelrc](https://docs.bazel.build/versions/master/user-manual.html#bazelrc).
 
-##### SNOPT
+## SNOPT
 
 Drake provides two mechanisms to include the SNOPT sources.  One mechanism is
 to provide your own SNOPT source archive.  The other mechanism is via access to
 a private RobotLocomotion git repository.
 
-###### Using your own source archive
+### Using your own source archive
 
 1. Download the SNOPT sources from the distributor in ``.tar.gz`` format (e.g.,
    named ``snopt7.4.tar.gz``).
@@ -239,14 +239,14 @@ See [https://docs.bazel.build/versions/master/user-manual.html#bazelrc](https://
 SNOPT support has some known problems on certain programs (see drake issue
 [#10422](https://github.com/RobotLocomotion/drake/issues/10422) for a summary).
 
-#### Optional Tools
+# Optional Tools
 
 The Drake Bazel build system has integration support for some optional
 development tools:
 
 * kcov -- test coverage analysis
 
-##### kcov
+## kcov
 
 ``kcov`` can analyze coverage for any binary that contains DWARF format
 debugging symbols, and produce nicely formatted browse-able coverage reports.

doc/buildcop.md → doc/_pages/buildcop.md

@@ -2,7 +2,7 @@
 title: Build Cop
 ---
 
-#### Overview
+# Overview
 
 The Drake build cop monitors [continuous](https://drake-jenkins.csail.mit.edu/view/Continuous%20Production/),
 [nightly](https://drake-jenkins.csail.mit.edu/view/Nightly%20Production/), and
@@ -16,7 +16,7 @@ The build cop will rotate on a weekly basis. The
 is maintained on the
 [RobotLocomotion/drake-ci](https://github.com/RobotLocomotion/drake-ci) wiki.
 
-#### Process
+# Process
 
 The build cop is expected to be on duty during normal business hours Eastern
 Time, approximately 9am to 5pm on weekdays, holidays excepted. Developers are
@@ -50,7 +50,7 @@ At the end of each rotation, the build cop should complete the
 [build cop review and retrospective](https://docs.google.com/document/d/120AOAaamIMO-SM1UaJ6vfzpA15LnXHexDF4a7MLAS3o/edit#heading=h.sxk1djc2v0yg),
 and should notify the next build cop on the [DrakeDevelopers Slack channel #buildcop](https://drakedevelopers.slack.com/messages/buildcop/details/).
 
-#### Revert Template
+# Revert Template
 
 When creating a revert PR, the build cop will assign that PR to the original
 author, and include the following template in the PR description.
@@ -93,7 +93,7 @@ author, and include the following template in the PR description.
  [2] https://drake.mit.edu/buildcop.html#workflow-for-handling-a-build-cop-revert
 ```
 
-#### Workflow for Handling a Build Cop Revert
+# Workflow for Handling a Build Cop Revert
 
 Suppose your merged PR was reverted on the master branch. What do you do?
 
@@ -110,11 +110,11 @@ Here's one workflow:
    PR in your new PR.
 
 
-#### Build Cop Playbook
+# Build Cop Playbook
 
 This section is a quick-reference manual for the on-call build cop.
 
-##### Monitor the Build
+## Monitor the Build
 
 Check the [Continuous Production](https://drake-jenkins.csail.mit.edu/view/Continuous%20Production/)
 build dashboard in Jenkins at least once an hour during on-call hours. These
@@ -133,7 +133,7 @@ color of the previous build.
 
 Note that CDash pages may take a minute to populate.
 
-##### Respond to Breakage
+## Respond to Breakage
 
 There are various reasons the build might break. Diagnose the failure, and
 then take appropriate action. This section lists some common failures and
@@ -153,7 +153,7 @@ such an issue, consider adding the build information to the issue for future
 analysis. The [build cop review and retrospective](https://docs.google.com/document/d/120AOAaamIMO-SM1UaJ6vfzpA15LnXHexDF4a7MLAS3o/edit#heading=h.sxk1djc2v0yg)
 also describes current build issues.
 
-##### Broken Compile or Test
+## Broken Compile or Test
 
 Sometimes people merge code that doesn't compile, or that fails a test.
 This can happen for several reasons:
@@ -176,7 +176,7 @@ proceed as specified in that message.
 experimental build on the rollback PR. If it passes, the odds are good that you
 have found the culprit. Proceed as specified in the template message.
 
-##### Flaky Test
+## Flaky Test
 
 Sometimes people introduce code that makes a test non-deterministic, failing
 on some runs and passing on others. You cannot reliably attribute a flaky test
@@ -190,7 +190,7 @@ After you identify one, create a rollback by clicking "Revert" in the
 GitHub UI. Use the [template message](/buildcop.html#revert-template) to communicate
 with the author, and proceed as specified in that message.
 
-##### Restarting Mac Nightly Builds
+## Restarting Mac Nightly Builds
 
 Occasionally there will be flaky tests or timeouts in the Mac nightly builds.
 While it is tempting to restart these builds to clear the errors, Mac resources
@@ -206,7 +206,7 @@ their best judgement, keeping in mind the following guidelines:
 * If the timed-out test failed last build (not just timed out), you may consider re-running.
 
 
-##### Broken CI Script
+## Broken CI Script
 
 Sometimes people merge changes to the Drake CI scripts that result in spurious
 CI failures. The list of commits in Jenkins for each continuous build includes
@@ -218,7 +218,7 @@ If they are not responsive, revert the commit yourself and see what happens on
 the next continuous build. There are no pre-merge builds you can run that
 exercise changes to the CI scripts themselves.
 
-##### Infrastructure Flake
+## Infrastructure Flake
 
 The machinery of the CI system itself sometimes fails for reasons unrelated to
 any code change. The most common infrastructure flakes include:
@@ -241,7 +241,7 @@ can be safely ignored.
 If you see "All nodes of label <label> are offline", this should disappear
 eventually and the build should run, once Jenkins gets a node booted up.
 
-##### Infrastructure Collapse
+## Infrastructure Collapse
 
 Occasionally, some piece of CI infrastructure completely stops working. For
 instance, GitHub, AWS, or MacStadium could have an outage, or our Jenkins server
@@ -253,7 +253,7 @@ alert Kitware by assigning a GitHub issue to both @BetsyMcPhail and
 @jamiesnape. If it's under a vendor's control, spread the news and simply wait
 it out.
 
-##### Drake External Examples
+## Drake External Examples
 
 Details of failures in the [drake-external-examples](https://github.com/RobotLocomotion/drake-external-examples/)
 repository, which may be denoted by red "build failing" icons at the top of the build