docs: add Usage section with 7 guides (#27)#36
Merged
shouze merged 5 commits intofeat/vitepress-docsfrom Feb 23, 2026
Merged
Conversation
- search-syntax.md: GitHub code search qualifiers, practical examples, API limits note - interactive-mode.md: TUI overview, keyboard shortcuts, filter mode, selection behaviour, full workflow example, output and replay command - non-interactive-mode.md: 3 ways to enable, GitHub Actions example, jq / shell tips - output-formats.md: markdown vs json, --output-type repo-and-matches / repo-only, summary line explained - filtering.md: --exclude-repositories, --exclude-extracts (with index warning), --include-archived, combining filters, in-TUI filter - team-grouping.md: --group-by-team-prefix, grouping algorithm, TUI sections, cache location/bypass/purge - upgrade.md: upgrade subcommand, --version, manual upgrade via install.sh - index.md: landing page listing all guides - getting-started/first-search.md: restore /usage/* links (pages now exist) - getting-started/index.md: add link to /usage/team-grouping for read:org scope row
There was a problem hiding this comment.
Pull request overview
Implements issue #27 by adding a complete Usage section to the VitePress docs, plus restoring/adding cross-links from Getting Started into the new guides.
Changes:
- Added 7 new usage guides under
docs/usage/(+ adocs/usage/index.mdlanding page). - Documented interactive/non-interactive workflows, filtering, output formats, team grouping, and upgrade behavior.
- Updated Getting Started pages to link to the new Usage guides.
Reviewed changes
Copilot reviewed 10 out of 10 changed files in this pull request and generated 13 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/usage/index.md | Adds a Usage section landing page with links to all guides. |
| docs/usage/search-syntax.md | Documents GitHub Code Search query syntax, qualifiers, and API limits. |
| docs/usage/interactive-mode.md | Documents the TUI layout, shortcuts, filtering, and replay output. |
| docs/usage/non-interactive-mode.md | Documents CI/non-interactive usage, replay commands, and piping output. |
| docs/usage/output-formats.md | Documents Markdown vs JSON output and --output-type. |
| docs/usage/filtering.md | Documents --exclude-repositories, --exclude-extracts, and --include-archived. |
| docs/usage/team-grouping.md | Documents --group-by-team-prefix, grouping behavior, and caching. |
| docs/usage/upgrade.md | Documents the upgrade subcommand, token usage, and manual upgrades. |
| docs/getting-started/index.md | Updates token scope table to link to the team grouping guide. |
| docs/getting-started/first-search.md | Restores “What’s next?” links to the new Usage guides. |
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
) Copilot review fixes: - search-syntax.md: add 'Restrict to specific repos' example showing repo: qualifiers interaction with --org (thread 2) - output-formats.md: - fix Markdown example: correct header (N files selected), add (N matches) suffix per repo, use ::: details for replay (thread 6) - fix repo-only Markdown: raw repo names only, no bullets, ::: details for replay (thread 7) - add --format json to replayCommand in JSON example (thread 9) - fix JSON repo-only: omit matches field, real selection.matches count (thread 3) - non-interactive-mode.md: - separate GitHub Actions YAML into its own yaml block (thread 8) - fix output header to 'N files selected', add (N matches) per repo (thread 11) - fix repo-only shell example to use --format json | jq - interactive-mode.md: fix output header and add (N matches) per repo (thread 10) - upgrade.md: fix output to match actual performUpgrade() messages (thread 4) - filtering.md: clarify --exclude-extracts index is position in API result list for the repo, not an occurrence index within the file (thread 12) VitePress fix: - output-formats.md: replace 4-backtick nested blocks containing <details> with plain 3-backtick text blocks + ::: details VitePress containers to prevent vue:compiler-core 'Invalid end tag' error
Comment on lines
+18
to
+29
| ```text | ||
| $ github-code-search upgrade | ||
| Checking for updates… | ||
| Already up to date (v1.2.0). | ||
| ``` | ||
|
|
||
| ```text | ||
| $ github-code-search upgrade | ||
| Checking for updates… | ||
| Upgrading v1.2.0 → v1.3.0… | ||
| Successfully upgraded to v1.3.0. | ||
| ``` |
There was a problem hiding this comment.
These example outputs don’t match the current performUpgrade messages: the CLI prints Already up to date (<currentVersion>) without a trailing period, and <currentVersion> comes from package.json (e.g. 1.2.0, not v1.2.0). Likewise the upgrade line will look like Upgrading 1.2.0 → v1.3.0… when the GitHub release tag has the v prefix. Please update the examples to reflect the exact strings users will see.
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 join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
Motivation
Fix #27 — the complete Usage section of the documentation site.
What changed
7 new guide pages under
docs/usage/:search-syntax.mdinteractive-mode.mdnon-interactive-mode.mdoutput-formats.md--format markdownvs--format jsonwith full examples,--output-type repo-and-matchesvsrepo-only, summary line semanticsfiltering.md--exclude-repositories,--exclude-extracts(format, index warning, how to find index),--include-archived, combining filters, difference vs in-TUI path filterteam-grouping.md--group-by-team-prefixoption, grouping algorithm (single/multi-prefix, combinations), TUI section separators, cache location/bypass/purgeupgrade.mdupgradesubcommand output, token requirement,--versionstring, manual upgrade viainstall.shPlus:
docs/usage/index.md— landing page for the sectiondocs/getting-started/first-search.md— restored/usage/*links (previously removed as dead — pages now exist)docs/getting-started/index.md—read:orgscope row now links to/usage/team-groupingHow to test
bun run docs:dev # → navigate to http://localhost:5173/github-code-search/usage/search-syntaxAll 7 pages should be reachable from the sidebar. Internal links (between Usage pages and from Getting Started) should resolve without 404.