Site: show top-level option next to flags on command line reference
- 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
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