fix: add troubleshooting and quick reference to docs file

[Flo4604]

What does this PR do?

Adds troubleshooting and quick reference to the docs.json

Type of change

• Bug fix (non-breaking change which fixes an issue)
• Chore (refactoring code, technical debt, workflow improvements)
• Enhancement (small improvements)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How should this be tested?

Checklist

Required

• Filled out the "How to test" section in this PR
• Read Contributing Guide
• Self-reviewed my own code
• Commented on my code in hard-to-understand areas
• Ran pnpm build
• Ran pnpm fmt
• Ran make fmt on /go directory
• Checked for warnings, there are none
• Removed all console.logs
• Merged the latest changes from main onto my branch with git pull origin main
• My changes don't cause any responsiveness issues

Appreciated

• If a UI change was made: Added a screen recording or screenshots to this PR
• Updated the Unkey Docs if changes were necessary

[changeset-bot]

⚠️ No Changeset found

Latest commit: 86b8927

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[vercel]

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

Project	Deployment	Preview	Comments	Updated (UTC)
dashboard	Ready	Preview	Comment	Nov 6, 2025 9:55am
engineering	Ready	Preview	Comment	Nov 6, 2025 9:55am

[coderabbitai]

📝 Walkthrough

Walkthrough

Two new analytics documentation pages are registered in the site configuration: quick-reference and troubleshooting. Additionally, formatting markers in the troubleshooting documentation are adjusted from checkmark/cross indicators to plus-dash notation.

Changes

Cohort / File(s)	Summary
Analytics documentation pages apps/docs/docs.json	Added analytics/quick-reference and analytics/troubleshooting entries to the Analytics group page list; adjusted formatting with trailing comma in analytics/query-restrictions to maintain valid JSON syntax.
Troubleshooting documentation annotations apps/docs/analytics/troubleshooting.mdx	Updated code block annotation line markers from "--- ❌ ..." / "--- ✅ ..." to "+-- ..." pattern across SQL blocks and JSON example sections (presentational only, no logic changes).

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

• Simple documentation configuration updates with no functional changes
• Formatting adjustments are purely visual markers within code blocks
• JSON syntax remains valid with minimal structural modifications

Possibly related PRs

• docs: clean up examples #4242: Modifies the same analytics documentation files (troubleshooting.mdx and docs.json analytics entries), indicating parallel or related documentation work.

Pre-merge checks and finishing touches

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description lacks critical details. The 'How should this be tested?' section is empty, and most required checklist items are unchecked, indicating incomplete verification of changes.	Fill in the 'How should this be tested?' section with clear testing instructions and verify all required checklist items before merging.
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Title check	✅ Passed	The pull request title accurately reflects the main change: adding troubleshooting and quick reference pages to the docs configuration file.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix/docs-missing-in-array

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between ecb4db7 and 86b8927.

📒 Files selected for processing (2)

• apps/docs/analytics/troubleshooting.mdx (3 hunks)
• apps/docs/docs.json (1 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: Docs
• GitHub Check: Analyze (javascript-typescript)

🔇 Additional comments (6)

apps/docs/analytics/troubleshooting.mdx (4)

35-42: Approve code example formatting updates.

The SQL comments demonstrating slow vs. fast query examples have been simplified while maintaining clarity. The markers clearly indicate the purpose of each example (slow/fast, wrong/correct). This formatting change improves readability without altering the technical content.

---

68-76: Approve JSON formatting updates.

The JSON comments showing incorrect and correct field names have been updated consistently. The examples clearly demonstrate the distinction between wrong (sql field) and correct (query field) request formats.

---

118-133: Approve SQL optimization example updates.

The "Filter Before Grouping" section has been reformatted to clearly contrast less efficient and more efficient query patterns. The simplified comment syntax maintains clarity while improving consistency with other examples in the document.

---

1-4: Frontmatter is correct and properly formatted.

The frontmatter in lines 1-4 is valid and aligns with the Mintlify docs structure. Cross-reference validation shows 8 of 9 links confirmed valid in docs.json. The one link appearing to fail (line 89: analytics/query-restrictions#function-allow-list) uses standard markdown fragment anchor syntax, which is a page-internal reference and does not require a separate docs.json entry. All documentation structure is sound.

apps/docs/docs.json (2)

174-182: JSON structure is valid.

The docs.json file parses correctly with the analytics page entries added.

---

174-182: No issues found—both referenced pages exist.

Verification confirms that both analytics/quick-reference.mdx and analytics/troubleshooting.mdx are present in the repository. All page references in the docs.json navigation configuration are valid and point to existing documentation files.

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

Thank you for following the naming conventions for pull request titles! 🙏

[graphite-app]

[graphite-app]

Graphite Automations

"Post a GIF when PR approved" took an action on this PR • (11/06/25)

1 gif was posted to this PR based on Andreas Thomas's automation.