Repository navigation
docs: consolidate Quick Start API key notes into tabbed engine selector - #43695
Conversation
…ck-start.mdx Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
This PR improves the Quick Start documentation by consolidating engine-specific secret setup instructions into a single tabbed selector, reducing visual noise and making it clearer that readers only need to follow one set of steps.
Changes:
- Replaces four sequential
> [!NOTE]callouts (one per engine secret) with a single<Tabs>/<TabItem>block. - Adds
Tabs/TabItemimport from@astrojs/starlight/componentsto support the new tabbed layout.
Show a summary per file
| File | Description |
|---|---|
| docs/src/content/docs/setup/quick-start.mdx | Replaces multiple engine secret callouts with a Starlight Tabs-based engine selector for credential setup instructions. |
Review details
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 1/1 changed files
- Comments generated: 3
- Review effort level: Low
| > 1. Create an API key in [Google AI Studio](https://aistudio.google.com/api-keys). | ||
| > 2. Add it as a repository secret from your repository root with `gh secret set GEMINI_API_KEY < /path/to/key.txt`, or use the GitHub UI. See [Authentication](/gh-aw/reference/auth/#gemini_api_key) for more detail. | ||
| > | ||
| **Setting up your API key?** Select the engine you chose above: |
|
🧠 Matt Pocock Skills Reviewer has completed the skills-based review. ✅ |
|
✅ Test Quality Sentinel completed test quality analysis. No test files were added or modified in this PR. Test Quality Sentinel skipped. |
|
✅ Design Decision Gate 🏗️ completed the design decision gate check. No ADR enforcement needed: PR does not have the 'implementation' label and has ≤100 new lines of code in business logic directories. |
|
✅ PR Code Quality Reviewer completed the code quality review. |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Clean, well-scoped docs improvement. The tabbed UI reduces cognitive load for beginners and the implementation is consistent with existing <Tabs> usage in the docs site. Content parity with the removed callouts is preserved, including the CODEX_API_KEY tip.
🧵 Reviewed using Impeccable skills by Impeccable Skills Reviewer · 19.4 AIC · ⌖ 6.29 AIC · ⊞ 4.9K
There was a problem hiding this comment.
Skills-Based Review 🧠
Applied /grill-with-docs — clean, well-motivated change with two minor suggestions.
📋 Key Themes & Highlights
Key Themes
- Minor wording improvement (line 88):
"Select the engine you chose above"depends on vertical position — suggest:"Select your engine:" - Opt-in UX win (line 90):
syncKey="engine"on<Tabs>enables cross-page tab sync at zero cost — worth adding before more engine-tabbed pages appear
Positive Highlights
- ✅ Great UX improvement — four stacked Note blocks replaced by a single focused tabbed selector
- ✅ Content fully preserved — no regressions possible
- ✅ Import pattern matches
creating-workflows.mdxandreusing-workflows.mdx - ✅ Tab labels match engine names used throughout the codebase
- ✅ The Codex
CODEX_API_KEYtip is correctly preserved inside its tab
🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer · 47.6 AIC · ⌖ 5.47 AIC · ⊞ 6.7K
Comment /matt to run again
| > 1. Create an API key in [Google AI Studio](https://aistudio.google.com/api-keys). | ||
| > 2. Add it as a repository secret from your repository root with `gh secret set GEMINI_API_KEY < /path/to/key.txt`, or use the GitHub UI. See [Authentication](/gh-aw/reference/auth/#gemini_api_key) for more detail. | ||
| > | ||
| **Setting up your API key?** Select the engine you chose above: |
There was a problem hiding this comment.
[/grill-with-docs] The phrase "Select the engine you chose above" relies on page position — on a long page or when linked directly, users may not recall which engine they chose earlier.
💡 Suggested wording
Something like:
Setting up your API key? Select the engine you configured in the wizard (Step 2 above):
or simply drop the locator and make it self-contained:
Setting up your API key? Select your engine:
The second option removes the dependency on vertical page context entirely and is safe regardless of how the user arrived at this section.
@copilot please address this.
There was a problem hiding this comment.
REQUEST_CHANGES
Two issues block merge. Both are already flagged in inline comments.
Blocking themes
1. Indentation breaks numbered step rendering (medium, UX-breaking)
The Markdown content inside every <TabItem> is indented 4 spaces. In Starlight's MDX processor, 4-space indent triggers a fenced code block in CommonMark, so users will see raw text instead of rendered numbered steps. Dedent to 0 or 2 spaces.
2. 'API key' intro is factually wrong for Copilot users (medium, accuracy)
The intro line reads 'Setting up your API key?' but the Copilot tab sets up COPILOT_GITHUB_TOKEN — a fine-grained PAT stored as a repository secret, not an API key. This will confuse Copilot users who look for where to obtain their 'API key'.
The UX improvement from consolidating four NOTE callouts into a single tabbed selector is sound; just fix the two issues above.
🔎 Code quality review by PR Code Quality Reviewer · 69.9 AIC · ⌖ 6.45 AIC · ⊞ 5.4K
Comment /review to run again
|
🎉 This pull request is included in a new release. Release: |
Four sequential collapsed Note blocks (one per engine API key) in Quick Start Step 2 created visual noise — beginners had no clear signal that they only need to action one of them.
Changes
docs/src/content/docs/setup/quick-start.mdx— Replaces the four> [!NOTE]callouts forCOPILOT_GITHUB_TOKEN,ANTHROPIC_API_KEY,OPENAI_API_KEY, andGEMINI_API_KEYwith a single<Tabs>component (one tab per engine). Adds theTabs/TabItemimport from@astrojs/starlight/components, consistent with existing usage increating-workflows.mdxandreusing-workflows.mdx.Tab content is identical to the original Note content for each engine.