docs preview: bazelbuild/bazel#29499

contribute/docs-contribution-workflow.mdx

@@ -0,0 +1,237 @@
+---
+title: 'Docs contribution workflow'
+---
+
+This page guides you through contributing to the Bazel
+documentation, from a one-line typo fix to adding a new page. For style
+guidance, see the [Bazel docs style guide](/contribute/docs-style-guide).
+
+## Bazel docs structure {#structure}
+
+The source of truth for Bazel documentation is `bazelbuild/bazel`, where docs
+live alongside the code. `bazel-contrib/bazel-docs` is the hosting and pipeline
+layer: it syncs content from `bazelbuild/bazel`, generates PR previews, and
+holds Mintlify configuration. **Content changes always go to `bazelbuild/bazel`.**
+
+| Repository | What it contains |
+|---|---|
+| [`bazelbuild/bazel`](https://github.com/bazelbuild/bazel) | All doc content (`docs/` folder). This is where you make changes. |
+| [`bazel-contrib/bazel-docs`](https://github.com/bazel-contrib/bazel-docs) | Hosting pipeline. Syncs from `bazelbuild/bazel`, generates PR previews, and deploys to [preview.bazel.build](https://preview.bazel.build). |
+<!-- TODO: Update preview.bazel.build to bazel.build once the domain cutover happens. Tracked in https://github.com/bazel-contrib/bazel-docs/issues/453 -->
+
+Bazel docs use [MDX format](https://mdxjs.com/), Markdown with a YAML
+frontmatter block at the top. Every page must start with:
+
+```
+---
+title: 'Your Page Title'
+---
+```
+
+## Prerequisites {#prerequisites}
+
+Before you start, you need:
+
+- A [GitHub account](https://github.com) 
+- A fork of [`bazelbuild/bazel`](https://github.com/bazelbuild/bazel)
+- [Git](https://git-scm.com/)
+- The [Mintlify CLI](https://www.mintlify.com/docs/cli/install) for local preview.  
+
+## Make a minor change {#quick-fix}
+
+For small isolated changes, such as a typo, broken link, phrasing tweaks, you can edit directly in the GitHub web UI without
+cloning anything.
+
+1. Find the file in
+   [`bazelbuild/bazel/docs/`](https://github.com/bazelbuild/bazel/tree/master/docs)
+   on GitHub.
+2. To edit the file, click the **pencil icon** in the top-right corner.
+3. Make your edit.
+4. Click **Commit changes...**, provide a commit message, and click **Propose changes"**.
+5. GitHub prompts you to open a pull request. Set the base branch to
+   **`master`** and click **Create pull request** it.
+
+## Update existing content {#updating-content}
+
+Use this workflow for anything larger than a typo, such as rewording a section,
+correcting outdated information, or adding a paragraph to an existing page.
+
+### Set up locally
+
+Fork [`bazelbuild/bazel`](https://github.com/bazelbuild/bazel) on GitHub first, then clone the repo and add the upstream remote:
+
+```bash
+git clone https://github.com/YOUR_USERNAME/bazel.git
+cd bazel
+git remote add upstream https://github.com/bazelbuild/bazel.git
+```
+
+### Make and preview your changes
+
+Check out a new branch off of `master`.
+
+```bash
+git fetch upstream
+git checkout -b my-doc-fix upstream/master
+```
+
+Edit the file in `docs/`, for example, `docs/concepts/labels.mdx`.
+
+To preview locally, you need a local copy of `bazel-contrib/bazel-docs`:
+
+```bash
+# One-time setup
+git clone https://github.com/bazel-contrib/bazel-docs.git
+cd bazel-docs
+```
+
+Copy your changed file(s) into the local `bazel-docs` mirror to preview them:
+
+```bash
+cp ~/path/to/bazel/docs/concepts/labels.mdx concepts/labels.mdx
+
+# Start the local dev server
+mintlify dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) to render your changes.
+
+### Commit and open a PR
+
+Add, commit, and push your changes:
+```bash
+git add --all # stage all changes 
+git commit -m "docs: your commit msg here"
+git push origin my-doc-fix # push to GitHub
+```
+
+Open a pull request on GitHub from your fork to **`bazelbuild/bazel` master**.
+
+## Add a new section to an existing page {#new-section}
+
+Follow the same workflow as [Update existing content](#updating-content). A few things to keep in mind:
+
+**Add a heading anchor ID.** Every heading should have an explicit `{#id}` so
+URLs to that section stay stable even if the heading text changes:
+
+```md
+## My new section {#my-new-section}
+```
+
+**Use sentence case for headings.** Write "Getting started" not
+"Getting Started".
+
+**Keep the heading hierarchy consistent.** Pages use H2 (`##`) for top-level
+sections and H3 (`###`) for subsections. Don't skip levels.
+
+**Update the page if there's a table of contents or "On this page" intro.**
+Some pages have an introductory list of topics. Add your section there too.
+
+## Add a new page {#new-page}
+
+1. Create the MDX file in the appropriate `docs/` subdirectory.
+   Every file must start with frontmatter:
+
+   ```
+   ---
+   title: 'Your Page Title'
+   ---
+   ```
+
+2. Add your page to the sidebar navigation. This requires a separate change
+   in `bazel-contrib/bazel-docs`. See
+   [Update the docs navigation](/contribute/docs-navigation) for instructions.
+   For an initial PR, you can skip this and ask a maintainer to help.
+
+3. Follow the same branch, commit, and PR steps as [Update existing content](#updating-content).
+
+## MDX basics for doc contributors {#mdx-basics}
+
+MDX is mostly standard Markdown with a few differences.
+
+### Self-closing HTML tags {#self-closing-tags}
+
+JSX requires void elements to be self-closing. Use `<img ... />` and
+`<br />`, not `<img ...>` or `<br>`.
+
+### Links {#links}
+
+Use root-relative paths for internal links. Don't include the `.mdx` extension in the links:
+
+```md
+[labels](/concepts/labels)
+[style guide](/contribute/docs-style-guide)
+```
+
+### Code blocks {#code-blocks}
+
+Always specify a language for syntax highlighting:
+
+````md
+```bash
+bazel build //my/example:app
+```
+````
+
+Common languages used in Bazel docs: `bash`, `python`, `starlark`, `json`,
+`posix-terminal`.
+
+### Images {#images}
+
+Place images in the `images/` subdirectory alongside your MDX file and
+reference them with a root-relative path:
+
+```md
+![Alt text](/contribute/images/my-diagram.png)
+```
+
+Use self-closing syntax: Markdown image syntax does not require the trailing `/>`, 
+but `<img>` tags must self-close when you use them directly:
+
+```md
+<img src="/contribute/images/my-diagram.png" alt="Alt text" width="400" />
+```
+
+### Notes and callouts {#callouts}
+
+Mintlify supports callout components. Use them for important warnings or tips:
+
+```md
+<Note>
+This is a note.
+</Note>
+
+<Warning>
+This is a warning.
+</Warning>
+```
+
+For a full list of Mintlify formatting components (tabs, accordions, cards,
+and more), see the [Mintlify text formatting docs](https://mintlify.com/docs/create/text).
+
+## What to expect after submitting {#after-submitting}
+
+- The Google CLA bot checks that you've signed the
+  [Contributor License Agreement](https://cla.developers.google.com/). You
+  only need to do this once.
+- CI runs a docs validation check.
+- A maintainer reviews your PR and might request edits. Response times vary.
+- Once approved, a maintainer merges your changes to `master`. They appear on
+  the live site after the next sync.
+
+<Tip>
+If your new page does not appear in the sidebar of the PR preview, use the
+black file-changes icon in the preview to navigate directly to it. New pages
+do not appear in the sidebar until you update the navigation in
+`bazel-contrib/bazel-docs`.
+</Tip>
+
+## Get help {#getting-help}
+
+- Join the [Bazel community Slack](https://slack.bazel.build) and ask in the
+  `#documentation` channel. This is the best place for quick questions about
+  the docs platform or contribution process.
+- File an issue in [`bazelbuild/bazel`](https://github.com/bazelbuild/bazel/issues)
+  with the label `type: documentation`.
+- For questions about the docs platform, open an
+  issue in [`bazel-contrib/bazel-docs`](https://github.com/bazel-contrib/bazel-docs/issues).

contribute/docs-navigation.mdx

@@ -0,0 +1,111 @@
+---
+title: '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 {#how-it-works}
+
+`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
+{
+  "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 {#prerequisites}
+
+- 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
+
+## Add a page to an existing group {#add-page}
+
+1. Clone your fork of `bazel-contrib/bazel-docs` and add the upstream remote:
+
+   ```bash
+   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
+   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
+   {
+     "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
+   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
+   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 {#add-group}
+
+If your new page does not fit into any existing group, add a new group object
+to the `navigation` array in `docs.json`:
+
+```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 {#getting-help}
+
+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).

reference/command-line-reference.mdx

@@ -1804,14 +1804,14 @@ Miscellaneous options, not otherwise categorized.:
 `--[no]show_timestamps` default: "false"
 :   Include timestamps in messages
 
-`--tls_certificate=<a string; empty to unset>` default: see description
-:   Specify a path to a TLS certificate that is trusted to sign server certificates. An empty value resets the flag to its default.
+`--tls_certificate=<a string>` default: see description
+:   Specify a path to a TLS certificate that is trusted to sign server certificates.
 
-`--tls_client_certificate=<a string; empty to unset>` default: see description
-:   Specify the TLS client certificate to use; you also need to provide a client key to enable client authentication. An empty value resets the flag to its default.
+`--tls_client_certificate=<a string>` default: see description
+:   Specify the TLS client certificate to use; you also need to provide a client key to enable client authentication.
 
-`--tls_client_key=<a string; empty to unset>` default: see description
-:   Specify the TLS client key to use; you also need to provide a client certificate to enable client authentication. An empty value resets the flag to its default.
+`--tls_client_key=<a string>` default: see description
+:   Specify the TLS client key to use; you also need to provide a client certificate to enable client authentication.
 
 `--ui_actions_shown=<an integer>` default: "8"
 :   Number of concurrent actions shown in the detailed progress bar; each action is shown on a separate line. The progress bar always shows at least one one, all numbers less than 1 are mapped to 1.
@@ -4587,12 +4587,6 @@ Remote caching and execution options:
 `--[no]remote_verify_downloads` default: "true"
 :   If set to true, Bazel will compute the hash sum of all remote downloads and discard the remotely cached values if they don't match the expected value.
 
-`--[no]rewind_lost_inputs` default: "false"
-:   Whether to use action rewinding to recover from lost inputs.
-
-    Tags:
-    [`execution`](#effect_tag_EXECUTION)
-
 Miscellaneous options, not otherwise categorized.:
 
 `--[no]allow_analysis_cache_discard` default: "true"

release/index.mdx

@@ -15,7 +15,7 @@ information about Bazel's release model.
 | ----------- | ------------- | -------------- | -------------- |
 | Bazel 10 | Rolling| [Check rolling release page](/release/rolling) | N/A |
 | Bazel 9 | Active| [9.1.0](https://github.com/bazelbuild/bazel/releases/tag/9.1.0) | Dec 2028 |
-| Bazel 8 | Maintenance| [8.7.0](https://github.com/bazelbuild/bazel/releases/tag/8.7.0) | Dec 2027 |
+| Bazel 8 | Maintenance| [8.6.0](https://github.com/bazelbuild/bazel/releases/tag/8.6.0) | Dec 2027 |
 | Bazel 7 | Maintenance| [7.7.1](https://github.com/bazelbuild/bazel/releases/tag/7.7.1) | Dec 2026 |
 | Bazel 6 | Deprecated | [6.6.0](https://github.com/bazelbuild/bazel/releases/tag/6.6.0) | Dec 2025 |
 | Bazel 5 | Deprecated | [5.4.1](https://github.com/bazelbuild/bazel/releases/tag/5.4.1) | Jan 2025 |