fix(misc): boost CLI command reference search ranking#34625
Merged
barbados-clemens merged 1 commit intomasterfrom Feb 27, 2026
Merged
Conversation
✅ Deploy Preview for nx-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Deploy Preview for nx-dev ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
barbados-clemens
force-pushed
the
feature/doc-401-investigate-boosting-cli-command-reference-pages-in-search
branch
from
e97804d to
e59d92d
Compare
Contributor
|
View your CI Pipeline Execution ↗ for commit 7d4021d
☁️ Nx Cloud last updated this comment at |
barbados-clemens
force-pushed
the
feature/doc-401-investigate-boosting-cli-command-reference-pages-in-search
branch
from
e59d92d to
73fa095
Compare
Add weight to the CLI commands page and lower term saturation so that searches like "nx watch" surface the command reference instead of being buried by shorter pages. Add command term into the sub headers as well for improved relevancy boosting
barbados-clemens
force-pushed
the
feature/doc-401-investigate-boosting-cli-command-reference-pages-in-search
branch
from
73fa095 to
7d4021d
Compare
Contributor
Author
|
example of search results w/ changes. (production (left) vs local changes (right) cli terms that improved terms w/ no impact (as expected) |
jaysoo
approved these changes
Feb 27, 2026
barbados-clemens
deleted the
feature/doc-401-investigate-boosting-cli-command-reference-pages-in-search
branch
jaysoo
pushed a commit
that referenced
this pull request
Feb 28, 2026
## Current Behavior Searching for CLI commands like `nx watch` on the docs site does not surface the [Nx Commands reference page](https://nx.dev/docs/reference/nx-commands) on the first page of results, even when filtering by "References." Root causes: - **Term saturation**: "nx" appears 150+ times on the CLI reference page (in every heading, usage block, and example), causing it to saturate and contribute almost nothing to ranking differentiation. - **Page length penalty**: The current `pageLength: 0.5` setting actively penalizes long pages—the CLI reference is one of the longest on the site. - **No weight boost**: The CLI page had no `weight` set, while generators/executors pages already get `weight: 2.0`. ## Expected Behavior Searching for `nx watch`, `nx run-many`, or other CLI commands should surface the Nx Commands reference page prominently in results. This PR applies two quick-win tuning changes: 1. **`weight: 4`** on the CLI commands page entry — gives body text ~16× impact (quadratic scaling), making it competitive with shorter pages that mention commands incidentally. include the command name in the sub headers for more improvement in relevancy search without impacting other pages 2. **`termSaturation: 1.2`** (down from default 1.4) — makes highly repeated terms like "nx" saturate faster so that the differentiating term (e.g. "watch") carries more relative weight. ## Related Issue(s) Addresses [DOC-401](https://linear.app/nxdev/issue/DOC-401/investigate-boosting-cli-command-reference-pages-in-search)
FrozenPandaz
pushed a commit
that referenced
this pull request
Mar 4, 2026
## Current Behavior Searching for CLI commands like `nx watch` on the docs site does not surface the [Nx Commands reference page](https://nx.dev/docs/reference/nx-commands) on the first page of results, even when filtering by "References." Root causes: - **Term saturation**: "nx" appears 150+ times on the CLI reference page (in every heading, usage block, and example), causing it to saturate and contribute almost nothing to ranking differentiation. - **Page length penalty**: The current `pageLength: 0.5` setting actively penalizes long pages—the CLI reference is one of the longest on the site. - **No weight boost**: The CLI page had no `weight` set, while generators/executors pages already get `weight: 2.0`. ## Expected Behavior Searching for `nx watch`, `nx run-many`, or other CLI commands should surface the Nx Commands reference page prominently in results. This PR applies two quick-win tuning changes: 1. **`weight: 4`** on the CLI commands page entry — gives body text ~16× impact (quadratic scaling), making it competitive with shorter pages that mention commands incidentally. include the command name in the sub headers for more improvement in relevancy search without impacting other pages 2. **`termSaturation: 1.2`** (down from default 1.4) — makes highly repeated terms like "nx" saturate faster so that the differentiating term (e.g. "watch") carries more relative weight. ## Related Issue(s) Addresses [DOC-401](https://linear.app/nxdev/issue/DOC-401/investigate-boosting-cli-command-reference-pages-in-search) (cherry picked from commit 7370195)
Contributor
|
This pull request has already been merged/closed. If you experience issues related to these changes, please open a new issue referencing this pull request. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Current Behavior
Searching for CLI commands like
nx watchon the docs site does not surface the Nx Commands reference page on the first page of results, even when filtering by "References."Root causes:
pageLength: 0.5setting actively penalizes long pages—the CLI reference is one of the longest on the site.weightset, while generators/executors pages already getweight: 2.0.Expected Behavior
Searching for
nx watch,nx run-many, or other CLI commands should surface the Nx Commands reference page prominently in results.This PR applies two quick-win tuning changes:
weight: 4on the CLI commands page entry — gives body text ~16× impact (quadratic scaling), making it competitive with shorter pages that mention commands incidentally. include the command name in the sub headers for more improvement in relevancy search without impacting other pagestermSaturation: 1.2(down from default 1.4) — makes highly repeated terms like "nx" saturate faster so that the differentiating term (e.g. "watch") carries more relative weight.Related Issue(s)
Addresses DOC-401