> ## Documentation Index
> Fetch the complete documentation index at: https://bazel-pr-30214.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Update the docs navigation

Add a new page to the Bazel docs sidebar, or
reorganize existing navigation groups. `bazel-contrib/bazel-docs` controls navigation, which is a separate repo from where doc content lives (`bazelbuild/bazel`).

<h2 id="how-it-works">
  How navigation works
</h2>

`docs.json` in [`bazel-contrib/bazel-docs`](https://github.com/bazel-contrib/bazel-docs)
defines the Bazel docs sidebar. Mintlify reads this file to build the
left-hand navigation tree.

`docs.json` contains a `navigation` array of groups, each with a list of pages:

```json theme={null}
{
  "navigation": [
    {
      "group": "Contribute",
      "pages": [
        "contribute/index",
        "contribute/docs-contribution-workflow",
        "contribute/docs-style-guide"
      ]
    }
  ]
}
```

Each entry in `pages` is a root-relative path to an `.mdx` file, without the
`.mdx` extension.

<h2 id="prerequisites">
  Prerequisites
</h2>

* A fork of [`bazel-contrib/bazel-docs`](https://github.com/bazel-contrib/bazel-docs)
* The [Mintlify CLI](https://www.mintlify.com/docs/cli/install) for local validation

<h2 id="add-page">
  Add a page to an existing group
</h2>

1. Clone your fork of `bazel-contrib/bazel-docs` and add the upstream remote:

   ```bash theme={null}
   git clone https://github.com/YOUR_USERNAME/bazel-docs.git
   cd bazel-docs
   git remote add upstream https://github.com/bazel-contrib/bazel-docs.git
   ```

2. Check out a new branch:

   ```bash theme={null}
   git fetch upstream
   git checkout -b add-my-page-to-nav upstream/main
   ```

3. Open `docs.json` and find the group where your page belongs. Add the
   path to the `pages` array:

   ```json theme={null}
   {
     "group": "Contribute",
     "pages": [
       "contribute/index",
       "contribute/docs-contribution-workflow",
       "contribute/docs-navigation",
       "contribute/docs-style-guide"
     ]
   }
   ```

4. Validate that `docs.json` is well-formed:

   ```bash theme={null}
   mint validate
   ```

   Run this from the `bazel-docs` root (where `docs.json` lives).

5. Commit and open a PR against `bazel-contrib/bazel-docs` main:

   ```bash theme={null}
   git add docs.json
   git commit -m "docs: Add my-page to navigation"
   git push origin add-my-page-to-nav
   ```

   Open a pull request targeting **`bazel-contrib/bazel-docs` main**.

<h2 id="add-group">
  Add a new navigation group
</h2>

If your new page does not fit into any existing group, add a new group object
to the `navigation` array in `docs.json`:

```json theme={null}
{
  "group": "My New Section",
  "pages": [
    "my-section/index",
    "my-section/getting-started"
  ]
}
```

Position it in the array where you want it to appear in the sidebar.

<h2 id="getting-help">
  Getting help
</h2>

If you are unsure where a page belongs, ask in the `#documentation` channel on
the [Bazel community Slack](https://slack.bazel.build) or open an issue in
[`bazel-contrib/bazel-docs`](https://github.com/bazel-contrib/bazel-docs/issues).