bazelbuild / bazelbuild/bazel

Site: show top-level option next to flags on command line reference

Open
#18,065 2 comments 1 reaction 0 assignees View on GitHub
P2 team-Documentation team-Remote-Exec type: documentation (cleanup)
Dominant language
Java
Stars
25.8k
Forks
4.6k
Avg merge
2d 20h
Merged PRs (30d)
72

Description

### Page link:

https://bazel.build/reference/command-line-reference

### Problem description (include actual vs expected text, if applicable):

When navigating to an anchor link, figuring out which top-level option (common, build, query, etc.) the flag belongs to is difficult. For example, when navigating to https://docs.bazel.build/versions/main/command-line-reference.html#flag--experimental_remote_build_event_upload, the only way to figure out the top-level option is to scroll up. Since the page is massive, it's easy to miss the top-level option.

The top-level option is important because I need to know it to update .bazelrc. For example, https://github.com/buildbuddy-io/buildbuddy/issues/3731

### Where do you see this issue? (include link to specific section of the page, if applicable)

https://docs.bazel.build/versions/main/command-line-reference.html#flag--experimental_remote_build_event_upload

### Any other information you'd like to share?

Some common patterns for improving positioning information for large pages like this:

1. Show the top-level option as a fixed header to the left when scrolling.
2. Show the top-level option on every flag.
3. Highlight the top-level option when scrolling.

Contributor guide

Open the contributing guide

Research direction

Start with the command-line reference page and the anchor for --experimental_remote_build_event_upload. Inspect how the page presents each flag and its top-level section, then choose a consistent way to keep that section visible or associated during navigation. Done means a reader can identify the top-level option from an anchored flag without scrolling through the page.

Written by the indexing model from the issue text.

Assessment

Domain
cli, documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.