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).

How navigation works

docs.json in 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:

{
  "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.

Prerequisites

• A fork of bazel-contrib/bazel-docs
• The Mintlify CLI for local validation

Add a page to an existing group

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

   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:

   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:

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

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

   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:

   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.

Add a new navigation group

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

{
  "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.

Getting help

If you are unsure where a page belongs, ask in the #documentation channel on the Bazel community Slack or open an issue in bazel-contrib/bazel-docs.