Bazel Docs

This repository contains the source and automated preview generation pipeline for the https://bazel.build/ website.

Contributing

Most changes to https://bazel.build/ should be made in the bazelbuild/bazel repository.

See Bazel's Docs contribution workflow for more information on how to make changes to Bazel's documentation site.

How to build the Bazel site locally

1. Clone the bazel-docs project:

   git clone https://github.com/bazel-contrib/bazel-docs.git && cd bazel-docs

   WARNING: Do not clone with --recurse-submodules or it will break the local preview generation. If you accidentally initialize the upstream submodule, you can deinitialize it with git submodule deinit -f --all.

2. If you haven't already, install npm.

3. Launch a local preview server with the following command:

   npx mint dev

   Example output

   $ npx mint dev
   Need to install the following packages:
   mint@4.2.679
   Ok to proceed? (y) y
   ✓ preview ready
   
     local   → http://localhost:3000
     network → http://192.168.1.4:3000
   
   press ctrl+c to exit the preview

How it works

Each branch pushed to this repo is automatically deployed by Mintlify at https://bazel-<branch-name>.mintlify.app. No additional configuration is required for preview deployments — the branch name determines the subdomain.

Files listed in .mintignore (gitignore syntax) are excluded from Mintlify rendering. Add files there when they contain MDX syntax errors that block deployment.

PR preview generation

The preview workflow (preview-bazel-docs-pr.yml) polls bazelbuild/bazel every 30 minutes for recently-updated open PRs. For each PR that has doc-related changes, it:

1. Creates or updates a pr-<N> branch in this repo with the PR's docs.
2. Mintlify deploys that branch at https://bazel-pr-<N>.mintlify.app.
3. Posts (or updates) a comment on the upstream PR with the preview link.

The preview workflow can be triggered manually from the GitHub Actions UI via workflow_dispatch without waiting for the 30-minute cron.

Updates to the live Bazel website

1. The upstream Git submodule tracks bazelbuild/bazel.
2. On every push to bazelbuild/bazel's main branch, a repository_dispatch event triggers this repo to sync the latest docs.
3. The sync workflow (pull-from-bazel-build.yml):
   • Copies .mdx files from upstream/docs/ directly into this repo.
   • Builds reference documentation (Starlark/Java API docs) via bazel build //...gen_mdx_reference_docs, which produces clean MDX directly via docs2mdx.py, and commits the result.
   • Commits the result and pushes to the appropriate branch.
4. Mintlify picks up the changes and deploys the updated docs site.
   • Files listed in .mintignore are excluded from Mintlify rendering. These are files with MDX syntax that cannot yet be auto-fixed (see #226).