feat(website/docs): docs index redesign with Start-here row and real item links

[ajitpratap0]

Summary

• Adds a Start here row (Getting Started, Usage Guide, CLI Guide) to /docs/.
• Every category card now lists all items as real links with the one-line description from DOCS_SIDEBAR; removes the '+N more' truncation and the single card-wide link.
• Cards get id anchors (docsCategoryAnchor helper); breadcrumb category on doc pages now links to /docs#.
• No CHANGELOG.md edit (per maintainer decision).

Test Plan

• cd website && npm ci && npm run typecheck && npm run lint && npm run build (pass; only pre-existing lint warnings)
• Check /docs/ lists all 24 docs as links; click breadcrumb category on any doc and land on the card.

Breaking Changes

None.

Closes #664
Part of #634

🤖 Generated with Claude Code

https://claude.ai/code/session_01RkzVu3JY9Y6BRWfjesWts9

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
gosqlx-website	Ready	Preview	Oct 14, 2026 7:07pm UTC

[github-actions]

Claude finished @ajitpratap0's task in 18s —— View job

---

PR review: docs index redesign

I read the diff and checked a few things against the code. I didn't run the build or lint, but your test plan says they pass.

Verdict: Looks good. Nothing blocks the merge.

What I checked

• Link is already imported in [...slug]/page.tsx, so the breadcrumb change compiles.
• All three START_HERE slugs (getting-started, usage-guide, cli-guide) exist in DOCS_SIDEBAR.
• The category anchors are unique. The seven categories slugify to getting-started, core, reference, advanced, tutorials, migration and editors.
• None of those collide with the start-here id, and none collide with the *-heading ids.
• scroll-mt-24 on the cards offsets the sticky header for the /docs#anchor jumps.
• aria-hidden on the decorative SVG and the aria-labelledby sections are good accessibility touches.

Minor suggestions (non-blocking)

1. getting-started is both a Start-here item and a category anchor. That's fine, since the ids are distinct (start-here vs getting-started). The page does show Getting Started twice, though, once in the Start-here row and again in its category card. That's probably intended.
2. START_HERE and ALL_ITEMS sit at module level. If someone renames a slug, the item is dropped silently by return null. A dev-time check would catch that earlier, for example a unit test that every START_HERE slug resolves.
3. The FadeIn wrapper animates opacity. If it starts at opacity 0 and only reveals when it scrolls into view, a /docs#editors jump may land on a card that hasn't faded in yet. This is cosmetic, so worth a quick manual check.
4. Each card's link block contains the full description, so a screen reader reads the label and the description as one link name. It's acceptable. aria-describedby on the link would separate the two if you want to tidy it.
5. There's no test for docsCategoryAnchor. It's a pure function, so a small unit test would be cheap if the website has a test setup.

Security and performance: No concerns. The page is static, the data is a build-time constant, and there's no user input.
· branch feat/docs-index-redesign

[vercel]

Deployment failed for project gosqlx-website with the following error:

Resource is limited - try again in 24 hours (more than 100, code: "api-deployments-free-per-day").

Learn More: https://vercel.com/coolajitpratapsingh0-9932s-projects?upgradeToPro=build-rate-limit

[github-actions]

Claude finished @ajitpratap0's task in 14s —— View job

---

PR review: docs index redesign

I read the diff (git diff origin/main...HEAD). I didn't run the build or lint. The test plan says they pass.

Verdict: Looks good. Nothing blocks the merge.

What I checked

• docsCategoryAnchor is a pure function. The category ids and the *-heading ids don't collide with start-here.
• The breadcrumb change in [...slug]/page.tsx swaps plain text for a Link to /docs#<anchor>. The Link import is already present there.
• Each card is now a <section> with aria-labelledby. The links inside it are real, so there are no nested anchors. Before this change the whole card was one link.
• The decorative SVG has aria-hidden, and scroll-mt-24 offsets the sticky header for anchor jumps.

Suggestions (non-blocking)

1. Silent drop in START_HERE (website/src/app/docs/page.tsx:25-27). If a slug is renamed, if (!item) return null hides the item with no error. A small test, or a throw at module level, would catch it.
2. FadeIn and anchor jumps. If FadeIn viewport starts at opacity 0 and reveals on scroll, a /docs#editors jump could land on a card that hasn't faded in yet. I didn't test this. Worth a quick manual check.
3. Link names. Each item link includes the label and the full description, so a screen reader reads both as one link name. Some descriptions are long (the JetBrains one is about 150 characters). Consider aria-describedby on the link, with the description outside the link text.
4. Duplicate entries. Getting Started, Usage Guide and CLI Guide now appear in both the Start-here row and their category cards. That's probably intended. The start-here heading and the getting-started category id are distinct, so there's no id clash.
5. No tests. docsCategoryAnchor has no unit test. Add one only if the website already has a test setup.

Security and performance: No concerns. The page is static and the data is a build-time constant.
· branch feat/docs-index-redesign