> ## Documentation Index > Fetch the complete documentation index at: https://bazel-promptless-add-bazel-online-flow-docs.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Contributing to bazel.online Documentation Documentation for bazel.online syncs automatically from the upstream Bazel repository (bazel.build) and transforms it for display on this site. ## Architecture overview ```mermaid theme={null} flowchart TB subgraph upstream["Upstream Repository (bazelbuild/bazel)"] A[site/en/*.md files] B[Bazel codebase with reference docs] end subgraph automation["Automation Pipeline"] C[GitHub Actions Workflow] D[copy-upstream-docs.sh] E[transform-docs.awk] F[docs.json.update.sh] end subgraph fork["This Fork (alan707/bazel-docs)"] G[*.mdx files] H[docs.json navigation] I[Mintlify deployment] end A -->|Synced via git submodule| C B -->|Built reference docs| C C -->|Executes| D D -->|Transforms .md → .mdx| E D -->|Updates navigation| F E -->|Generates| G F -->|Updates| H G -->|Deployed to| I H -->|Configures| I I -->|Published at| J[bazel.online] style upstream fill:#e1f5ff style fork fill:#d4edda style automation fill:#fff3cd ``` ## The documentation flow ### Upstream source (bazel.build) The canonical source for Bazel documentation lives in the [bazelbuild/bazel](https://github.com/bazelbuild/bazel) repository: * **Narrative documentation**: `.md` files in the `site/en/` directory * **Reference documentation**: Generated from code comments in the Bazel codebase Make changes to the upstream Bazel repository, not to this fork directly. ### Automated synchronization A GitHub Actions workflow (`.github/workflows/pull-from-bazel-build.yml`) syncs the upstream repository periodically: * Initializes the `upstream` git submodule pointing to bazelbuild/bazel * Builds reference documentation from the Bazel codebase * Runs `copy-upstream-docs.sh` to copy and transform files * Uses `transform-docs.awk` to convert `.md` files to Mintlify-compatible `.mdx` format * Updates `docs.json` with versioned navigation structures * Commits and pushes changes to this repository **When it runs:** * Automatically when Dependabot updates the upstream submodule * Manually via workflow dispatch * On pull requests to preview changes ### Documentation transformation The transformation process adapts upstream documentation for Mintlify: **File conversion (`.md` → `.mdx`):** * Converts HTML tags to Mintlify components * Transforms anchor references (underscores to dashes) * Adds frontmatter for Mintlify * Preserves code examples and syntax highlighting **Navigation structure:** * Upstream uses `_index.yaml` files for navigation * This fork uses `docs.json` (Mintlify format) * Navigation changes must be manually applied to maintain consistency ### Preview and deployment (bazel.online) Once changes merge into this repository: * **Preview**: Pull requests generate preview deployments via Mintlify automatically * **Production**: Merges to `main` deploy to bazel.online * **Versioned docs**: Multiple Bazel versions are maintained (6.5.0, 7.6.1, 8.x.x, etc.) ## Contributing documentation ### Making changes **For narrative documentation:** 1. Make your changes in the [bazelbuild/bazel](https://github.com/bazelbuild/bazel) repository 2. Edit files in the `site/en/` directory 3. Create a pull request following the upstream contribution guidelines 4. Once merged, your changes sync to bazel.online automatically **For reference documentation:** 1. Update code comments in the relevant Bazel source files 2. The build process extracts and formats the documentation automatically ### Local-only files Some files live only in this repository and don't sync from upstream: * `index.mdx` (homepage) * `docs.json` (navigation configuration) * Files listed in the `LOCAL_FILES` variable in `copy-upstream-docs.sh` Make changes to these files directly in this repository. ## Seeing your changes ### During development **Upstream PR preview:** * When you create a PR in bazelbuild/bazel, changes don't appear on bazel.online yet * Review the Markdown files in the GitHub PR interface * Ensure your documentation follows Markdown best practices **This repository preview:** * After your upstream changes sync here, a PR is created automatically * Mintlify generates a preview deployment for the PR * You can review the rendered documentation on bazel.online's preview URL ### After merging **Timeline:** 1. Your PR merges to bazelbuild/bazel (bazel.build) 2. Dependabot detects the upstream changes (runs periodically) 3. Automation creates a PR in this repository 4. After review and merge, changes deploy to bazel.online (typically within minutes) **Verification:** * Visit [bazel.online](https://bazel.online) to see your published changes * Check both current version and versioned documentation paths * Use the site search to find your updated content ## Troubleshooting ### My upstream PR merged but I don't see it on bazel.online The sync process runs periodically via Dependabot. It may take time for: * Dependabot to detect upstream changes * The sync PR to be created and reviewed * The changes to be merged and deployed ### The documentation looks different on bazel.online The transformation process converts Markdown to Mintlify-flavored MDX. Some differences are expected: * HTML tags convert to Mintlify components (for example, `