docs: unified IA + robust README + VitePress categories#694
Conversation
Co-authored-by: Codex <noreply@openai.com>
|
Warning You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again! |
📝 WalkthroughWalkthroughDocumentation restructuring for CLIProxyAPI++ project encompassing README overhaul, VitePress configuration updates, theme simplification, and content reorganization across API and homepage documentation files to streamline navigation structure and presentation. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/.vitepress/config.ts`:
- Line 9: Remove the ignoreDeadLinks: true setting from the VitePress config so
dead-link checking is enabled; locate the ignoreDeadLinks property in the
exported config object (the ignoreDeadLinks entry) and delete that line (or set
it to false) to restore strict link validation during builds.
In `@docs/.vitepress/theme/index.ts`:
- Around line 8-10: Replace the current pattern of spreading DefaultTheme with
proper theme composition by using extends: DefaultTheme and defining enhanceApp
alongside it so VitePress will automatically call the parent theme's enhanceApp;
remove the ...DefaultTheme spread, keep your enhanceApp implementation that
registers CategorySwitcher via app.component('CategorySwitcher',
CategorySwitcher), and ensure the export uses extends: DefaultTheme to compose
themes correctly.
In `@docs/api/index.md`:
- Around line 5-7: The index currently lists plain text entries
("OpenAPI/Swagger artifacts", "SDK references", "Endpoint guides") that are not
navigable; change each list item in docs/api/index.md to a proper Markdown link
pointing to the corresponding documentation pages (e.g., the OpenAPI artifacts
page, SDK reference page, and endpoint guides page) using the correct relative
paths or permalinks so users can click through, and verify the target files
exist and front-matter/slug matches the link targets.
In `@README.md`:
- Line 57: The README's "unified category IA" section is inconsistent with the
earlier reference to docs/operations/ and docs/reference/; update the "unified
category IA" list (the section around the "unified category IA" heading) to
include docs/operations/ and docs/reference/, or alternatively add a clarifying
sentence there explaining that operations and reference are intentionally
maintained outside the canonical IA and why; ensure you edit the README.md
entries that enumerate documentation directories so the listed directories and
the explanatory text match.
ℹ️ Review info
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (5)
README.mddocs/.vitepress/config.tsdocs/.vitepress/theme/index.tsdocs/api/index.mddocs/index.md
📜 Review details
🔇 Additional comments (3)
docs/index.md (1)
1-13: Clean and coherent landing-page simplification.The CategorySwitcher + top-level category links are clear and aligned with the new unified IA.
README.md (1)
5-14: Strong README restructuring.The new sectioning and navigation make onboarding and operations context much easier to scan.
Also applies to: 16-56, 59-94
docs/.vitepress/config.ts (1)
4-8: Navigation structure is well organized.The per-path sidebar buckets and top-level nav align cleanly with the unified IA.
Also applies to: 10-63
| srcDir: '.', | ||
| lastUpdated: true, | ||
| cleanUrls: true, | ||
| ignoreDeadLinks: true, |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
VitePress ignoreDeadLinks configuration behavior and best practices
💡 Result:
What ignoreDeadLinks does (behavior)
- Default:
false→ VitePress fails the production build when it detects dead links. [1] (vitepress.dev) true→ VitePress does not fail builds due to dead links (the check is effectively disabled for build-failing purposes). [1] (vitepress.dev)'localhostLinks'→ VitePress still fails on dead links, but skips checking links tolocalhost. [1] (vitepress.dev)- Array form → instead of disabling checks globally, you can ignore specific links by:
- exact string match,
RegExp,- custom predicate function. [1] (vitepress.dev)
Type (from docs):
boolean | 'localhostLinks' | (string | RegExp | ((link: string, source: string) => boolean))[] [1] (vitepress.dev)
Recommended best practices
-
Keep dead-link failures enabled in CI (recommended default)
LeaveignoreDeadLinks: falseso broken internal docs links block merges/releases. This is VitePress’s intended “strict by default” workflow. [1] (vitepress.dev) -
Prefer the array form over
true(avoid hiding real regressions)
Use targeted ignores for known/intentional cases (generated pages, placeholders, etc.). The docs explicitly support strings/regex/functions for this. [1] (vitepress.dev) -
Use
'localhostLinks'when you intentionally include local-only links
Example: contributor docs that link tohttp://localhost:xxxxfor local services—skip those without disabling the rest of the check. [1] (vitepress.dev) -
Make ignores explicit and reviewable
- Prefer narrow regexes (match only what you must).
- If using a function, consider using both
linkandsource(the file) to scope exceptions to specific pages (the function signature includessource). [1] (vitepress.dev)
Example configurations
Strict CI (recommended)
// .vitepress/config.ts
export default {
// default behavior (can be omitted)
ignoreDeadLinks: false
}[1] (vitepress.dev)
Allow localhost links, fail on everything else
export default {
ignoreDeadLinks: 'localhostLinks'
}[1] (vitepress.dev)
Targeted ignores (most common “best practice” setup)
export default {
ignoreDeadLinks: [
'/playground', // exact
/^https?:\/\/localhost/, // regex
/\/repl\//, // regex
(link, source) => source.endsWith('WIP.md') // function (scoped)
]
}(Exact/regex/function patterns are supported as shown in the docs.) [1] (vitepress.dev)
Citations:
- 1: https://vitepress.dev/reference/site-config?utm_source=openai
- 2: https://vitepress.dev/reference/site-config?utm_source=openai
- 3: https://vitepress.dev/reference/site-config?utm_source=openai
- 4: https://vitepress.dev/reference/site-config?utm_source=openai
- 5: https://vitepress.dev/reference/site-config?utm_source=openai
- 6: https://vitepress.dev/reference/site-config?utm_source=openai
- 7: https://vitepress.dev/reference/site-config?utm_source=openai
- 8: https://vitepress.dev/reference/site-config?utm_source=openai
- 9: https://vitepress.dev/reference/site-config?utm_source=openai
- 10: https://vitepress.dev/reference/site-config?utm_source=openai
- 11: https://vitepress.dev/reference/site-config?utm_source=openai
- 12: https://vitepress.dev/reference/site-config?utm_source=openai
🏁 Script executed:
# Check if ignoreDeadLinks was already in config before this change
git log --oneline -n 20 docs/.vitepress/config.ts 2>/dev/null | head -10Repository: KooshaPari/cliproxyapi-plusplus
Length of output: 135
🏁 Script executed:
# Check current state of the config file to understand context
head -20 docs/.vitepress/config.tsRepository: KooshaPari/cliproxyapi-plusplus
Length of output: 635
Remove ignoreDeadLinks: true to catch broken routes during this IA migration.
Setting ignoreDeadLinks: true disables dead-link detection in the build entirely. VitePress's default (false) enforces strict link checking—the recommended practice for CI. During a major navigation restructure, disabled link validation risks masking broken routes that should block the merge. Either remove the setting (defaults to strict checking) or use targeted ignores if specific links must be skipped.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/.vitepress/config.ts` at line 9, Remove the ignoreDeadLinks: true
setting from the VitePress config so dead-link checking is enabled; locate the
ignoreDeadLinks property in the exported config object (the ignoreDeadLinks
entry) and delete that line (or set it to false) to restore strict link
validation during builds.
| enhanceApp({ app }) { | ||
| app.component('CategorySwitcher', CategorySwitcher) | ||
| }, |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
🧩 Analysis chain
🌐 Web query:
VitePress custom theme enhanceApp override DefaultTheme chaining best practice
💡 Result:
Best practice: use VitePress’ built-in theme chaining via extends: DefaultTheme and put your additions in your enhanceApp. When you use extends, VitePress will call the parent theme’s enhanceApp before yours automatically—so you generally should not manually call DefaultTheme.enhanceApp(...). [1]
// .vitepress/theme/index.ts
import type { Theme } from 'vitepress'
import DefaultTheme from 'vitepress/theme'
import Foo from './Foo.vue'
export default {
extends: DefaultTheme,
enhanceApp({ app }) {
// DefaultTheme.enhanceApp runs first automatically because of `extends`
app.component('Foo', Foo)
}
} satisfies ThemeAvoid this common pitfall: export default { ...DefaultTheme, enhanceApp() { ... } } does not express “call DefaultTheme then mine”; it just replaces properties, and you can accidentally drop/overwrite behavior instead of cleanly chaining. Prefer extends for composition. [1][2]
If you also need to customize layout, keep extends: DefaultTheme and override Layout (e.g., wrap DefaultTheme.Layout)—you still get the chained enhanceApp. [2][3]
Sources: [1] VitePress “Using a Custom Theme” (theme interface + extends calling order), [2] VitePress “Extending the Default Theme”, [3] VitePress default theme layout reference example.
Refactor to use extends for proper theme composition instead of spreading DefaultTheme.
The current pattern using ...DefaultTheme is a common pitfall that doesn't automatically chain enhanceApp. VitePress provides the extends property to properly compose themes—when you use extends: DefaultTheme, VitePress automatically calls the parent theme's enhanceApp before yours, so default behavior is preserved without manual chaining.
Suggested fix
-const theme: Theme = {
- ...DefaultTheme,
+const theme: Theme = {
+ extends: DefaultTheme,
enhanceApp({ app }) {
app.component('CategorySwitcher', CategorySwitcher)
},
- Layout: DefaultTheme.Layout
}🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/.vitepress/theme/index.ts` around lines 8 - 10, Replace the current
pattern of spreading DefaultTheme with proper theme composition by using
extends: DefaultTheme and defining enhanceApp alongside it so VitePress will
automatically call the parent theme's enhanceApp; remove the ...DefaultTheme
spread, keep your enhanceApp implementation that registers CategorySwitcher via
app.component('CategorySwitcher', CategorySwitcher), and ensure the export uses
extends: DefaultTheme to compose themes correctly.
| - OpenAPI/Swagger artifacts | ||
| - SDK references | ||
| - Endpoint guides |
There was a problem hiding this comment.
Make API index entries navigable.
Line 5–Line 7 are non-clickable labels, so this “index” page cannot actually route users to API docs.
Suggested fix
-- OpenAPI/Swagger artifacts
-- SDK references
-- Endpoint guides
+- [OpenAPI/Swagger artifacts](/api/openapi/)
+- [SDK references](/api/sdk/)
+- [Endpoint guides](/api/endpoints/)📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - OpenAPI/Swagger artifacts | |
| - SDK references | |
| - Endpoint guides | |
| - [OpenAPI/Swagger artifacts](/api/openapi/) | |
| - [SDK references](/api/sdk/) | |
| - [Endpoint guides](/api/endpoints/) |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/api/index.md` around lines 5 - 7, The index currently lists plain text
entries ("OpenAPI/Swagger artifacts", "SDK references", "Endpoint guides") that
are not navigable; change each list item in docs/api/index.md to a proper
Markdown link pointing to the corresponding documentation pages (e.g., the
OpenAPI artifacts page, SDK reference page, and endpoint guides page) using the
correct relative paths or permalinks so users can click through, and verify the
target files exist and front-matter/slug matches the link targets.
| - Rate limiting and quota/cooldown controls. | ||
| - Auth flows for provider-specific OAuth/API keys. | ||
| - CI policy checks and path guards. | ||
| - Governance and security docs under `docs/operations/` and `docs/reference/`. |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Check which documentation directories exist
for p in docs/operations docs/reference docs/wiki docs/development docs/index docs/api docs/roadmap; do
if [ -e "$p" ]; then
echo "FOUND $p"
else
echo "MISSING $p"
fi
doneRepository: KooshaPari/cliproxyapi-plusplus
Length of output: 221
🏁 Script executed:
# Verify the exact content at line 57 and surrounding context
sed -n '50,65p' README.mdRepository: KooshaPari/cliproxyapi-plusplus
Length of output: 447
🏁 Script executed:
# Search for all documentation path references in README.md
grep -n "docs/" README.md | head -20Repository: KooshaPari/cliproxyapi-plusplus
Length of output: 316
Resolve inconsistency between governance docs reference and unified IA definition.
Line 57 correctly references docs/operations/ and docs/reference/ (both exist), but the "unified category IA" definition on lines 71–75 omits these directories and lists others that don't exist (docs/wiki/, docs/development/, docs/index/, docs/roadmap/). Either the unified IA should include operations and reference, or clarify why they exist outside the canonical structure. This inconsistency can confuse contributors about the actual documentation organization.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@README.md` at line 57, The README's "unified category IA" section is
inconsistent with the earlier reference to docs/operations/ and docs/reference/;
update the "unified category IA" list (the section around the "unified category
IA" heading) to include docs/operations/ and docs/reference/, or alternatively
add a clarifying sentence there explaining that operations and reference are
intentionally maintained outside the canonical IA and why; ensure you edit the
README.md entries that enumerate documentation directories so the listed
directories and the explanatory text match.
1 participant
Implements Wave 1 docs unification for CLIProxyAPI++:\n\n- upgrades README to robust structure\n- standardizes docs IA: Wiki, Development Guide, Document Index, API, Roadmap\n- adds sidebar category switcher component\n- adds document index buckets (raw-all/planning/specs/research/worklogs/other)\n- adds docs index generator script\n- adds roadmap and API landing pages\n
Summary by CodeRabbit