docs: redesign documentation site into guide + package reference - #756
Merged
Conversation
- restructure into a learning-path Guide (introduction, essentials, parameters, digging deeper, recipes, migration) and a per-package reference section (/packages/) - add new pages: core concepts, wire/transport, executing queries, error handling, three recipes (express-typeorm, frontend, authorization) and split migration guides (v1, typeorm-extension) - add @rapiq/core reference page; split the URL codec page per package - replace ascii diagrams with theme-aware Vue figures (QueryPipeline, QueryHub, PackageLayers) - keep old URLs working via meta-refresh redirect stubs (published package READMEs link to them) - point root & package README doc links at the new canonical URLs
📝 WalkthroughWalkthroughThe documentation site is reorganized around ChangesDocumentation v2 information architecture
Estimated code review effort: 4 (Complex) | ~60 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ 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: 6
🧹 Nitpick comments (2)
packages/docs/guide/filters.md (1)
42-49: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueSpecify a language for the fenced code block.
The code block at line 42 has no language specifier, triggering markdownlint MD040. Since this is wire-format example text (not executable code),
textis the appropriate language.📝 Proposed fix
-filter[id]=1 equal
+```text
+filter[id]=1 equal
filter[name]=jocontains</details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.In
@packages/docs/guide/filters.mdaround lines 42 - 49, Specify the text
language for the fenced code block containing the filter examples in the filters
documentation, using a text fence while preserving all example content and
formatting.</details> <!-- cr-comment:v1:ce9d8a1b62b17ce1d73182df --> _Source: Linters/SAST tools_ </blockquote></details> <details> <summary>packages/docs/guide/recipes/frontend.md (1)</summary><blockquote> `79-81`: _🩺 Stability & Availability_ | _🔵 Trivial_ | _⚡ Quick win_ **Prevent stale requests from overwriting newer results.** `watchEffect(async () => ...)` allows an earlier, slower response to replace results from a newer search or page. Use an `AbortController` or Vue cleanup callback before assigning `users.value`. <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.In
@packages/docs/guide/recipes/frontend.mdaround lines 79 - 81, Update the
watchEffect around the users fetch to cancel or invalidate the previous request
during cleanup, and ensure its response is only assigned to users.value if it is
still current. Preserve the existing queryString-driven fetch behavior while
preventing slower responses from overwriting newer results.</details> <!-- cr-comment:v1:6c1103cecf9a44f4c6f24f5a --> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.Inline comments:
In@packages/docs/guide/building-queries.md:
- Around line 8-14: Make the introductory defineQuery example self-contained by
replacing the undeclared text and id references in the filters with
representative literals, or declare both values before the query. Keep the
existing query structure and TypeScript validity intact.In
@packages/docs/guide/index.md:
- Around line 7-9: Specify the fenced code block language for the URL-query
example in the documentation, using text (or an equivalent plain-text language)
to satisfy Markdown linting while preserving the example content.In
@packages/docs/guide/quick-start.md:
- Line 44: Update the filter example in the quick-start guide to use the
schema’s declared User field, realm, instead of realm_id. Keep the array/in-list
demonstration and ensure the referenced field is included in the allowed filter
configuration.In
@packages/docs/guide/recipes/frontend.md:
- Around line 39-51: Update the recipe’s query-building flow to accept realmId
explicitly rather than referencing undeclared props: add realmId to buildQuery
or fetchUsers, use that parameter when defining the scope, and pass it through
from each framework adapter. Preserve the existing merge precedence and query
behavior.In
@packages/docs/packages/typeorm.md:
- Line 72: Update the terminology in the TypeORM adapter documentation around
the dialect and operator description so “regex” and “regexp” are used
consistently throughout the page. Choose one term, replace the inconsistent
occurrence(s), and preserve the existing behavior and operator names where they
are part of the documented API.In
@README.md:
- Line 87: Correct the condition helpers Markdown link target in the README,
replacing the malformedbuilding-queriesing-queriespath with the documented
condition-helpers URL while preserving the existing link text and surrounding
content.
Nitpick comments:
In@packages/docs/guide/filters.md:
- Around line 42-49: Specify the text language for the fenced code block
containing the filter examples in the filters documentation, using a text fence
while preserving all example content and formatting.In
@packages/docs/guide/recipes/frontend.md:
- Around line 79-81: Update the watchEffect around the users fetch to cancel or
invalidate the previous request during cleanup, and ensure its response is only
assigned to users.value if it is still current. Preserve the existing
queryString-driven fetch behavior while preventing slower responses from
overwriting newer results.</details> <details> <summary>🪄 Autofix (Beta)</summary> Fix all unresolved CodeRabbit comments on this PR: - [ ] <!-- {"checkboxId": "4b0d0e0a-96d7-4f10-b296-3a18ea78f0b9"} --> Push a commit to this branch (recommended) - [ ] <!-- {"checkboxId": "ff5b1114-7d8c-49e6-8ac1-43f82af23a33"} --> Create a new PR with the fixes </details> --- <details> <summary>ℹ️ Review info</summary> <details> <summary>⚙️ Run configuration</summary> **Configuration used**: defaults **Review profile**: CHILL **Plan**: Pro **Run ID**: `53d877ac-9b4a-41a0-8acb-c4f0f455e199` </details> <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between ff800701c38e43298e09bc2c104153eb3a3ddd25 and 2a203f85664f5391ce9af23aa3d2aca88b6e10a4. </details> <details> <summary>📒 Files selected for processing (67)</summary> * `README.md` * `packages/codec-url-expression/README.md` * `packages/codec-url-simple/README.md` * `packages/codec-url/README.md` * `packages/core/README.md` * `packages/docs/.vitepress/config.mjs` * `packages/docs/.vitepress/theme/components/Hero.vue` * `packages/docs/.vitepress/theme/components/PackageLayers.vue` * `packages/docs/.vitepress/theme/components/PackageShowcase.vue` * `packages/docs/.vitepress/theme/components/QueryHub.vue` * `packages/docs/.vitepress/theme/components/QueryPipeline.vue` * `packages/docs/.vitepress/theme/components/TypeormSection.vue` * `packages/docs/.vitepress/theme/index.ts` * `packages/docs/getting-started/index.md` * `packages/docs/getting-started/installation.md` * `packages/docs/getting-started/quick-start.md` * `packages/docs/guide/build.md` * `packages/docs/guide/building-queries.md` * `packages/docs/guide/concepts.md` * `packages/docs/guide/errors.md` * `packages/docs/guide/executing-queries.md` * `packages/docs/guide/fields.md` * `packages/docs/guide/filters.md` * `packages/docs/guide/index.md` * `packages/docs/guide/installation.md` * `packages/docs/guide/merge.md` * `packages/docs/guide/merging-queries.md` * `packages/docs/guide/migration-typeorm-extension.md` * `packages/docs/guide/migration-v1.md` * `packages/docs/guide/migration.md` * `packages/docs/guide/pagination.md` * `packages/docs/guide/query-ast.md` * `packages/docs/guide/query.md` * `packages/docs/guide/quick-start.md` * `packages/docs/guide/recipes/authorization.md` * `packages/docs/guide/recipes/express-typeorm.md` * `packages/docs/guide/recipes/frontend.md` * `packages/docs/guide/relations.md` * `packages/docs/guide/schema.md` * `packages/docs/guide/schemas.md` * `packages/docs/guide/sort.md` * `packages/docs/guide/wire.md` * `packages/docs/integrations/expression.md` * `packages/docs/integrations/index.md` * `packages/docs/integrations/memory.md` * `packages/docs/integrations/mongo.md` * `packages/docs/integrations/simple.md` * `packages/docs/integrations/sql.md` * `packages/docs/integrations/typeorm.md` * `packages/docs/integrations/url.md` * `packages/docs/packages/codec-url-expression.md` * `packages/docs/packages/codec-url-simple.md` * `packages/docs/packages/codec-url.md` * `packages/docs/packages/core.md` * `packages/docs/packages/index.md` * `packages/docs/packages/memory.md` * `packages/docs/packages/parser-expression.md` * `packages/docs/packages/parser-mongo.md` * `packages/docs/packages/parser-simple.md` * `packages/docs/packages/sql.md` * `packages/docs/packages/typeorm.md` * `packages/memory/README.md` * `packages/parser-expression/README.md` * `packages/parser-mongo/README.md` * `packages/parser-simple/README.md` * `packages/sql/README.md` * `packages/typeorm/README.md` </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
- fix mangled condition-helpers link in root README - make defineQuery intro example self-contained (literals instead of undeclared variables); use relation path realm.id instead of the undeclared realm_id field in filter examples - thread realmId explicitly through the frontend recipe instead of reading an undeclared props object - add language tags to bare fenced code blocks (MD040) - use 'regex' consistently in prose (regexp stays for the DialectOptions callback and SQL REGEXP)
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
packages/docs/packages/sql.md (1)
41-41: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winInclude the filters adapter/visitor pair in the root adapter list.
This sentence lists only four pairs but then says the root
Adapterbundles five. AddFiltersAdapter/FiltersVisitorso the architecture description matches the documented API.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/docs/packages/sql.md` at line 41, Update the adapter/visitor pair list in the SQL documentation to include FiltersAdapter/FiltersVisitor, so it lists all five pairs bundled by the root Adapter and remains consistent with the documented API.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Outside diff comments:
In `@packages/docs/packages/sql.md`:
- Line 41: Update the adapter/visitor pair list in the SQL documentation to
include FiltersAdapter/FiltersVisitor, so it lists all five pairs bundled by the
root Adapter and remains consistent with the documented API.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 93f81237-07f1-4166-8a36-23daefa81963
📒 Files selected for processing (14)
README.mdpackages/docs/guide/building-queries.mdpackages/docs/guide/errors.mdpackages/docs/guide/fields.mdpackages/docs/guide/filters.mdpackages/docs/guide/index.mdpackages/docs/guide/pagination.mdpackages/docs/guide/quick-start.mdpackages/docs/guide/recipes/express-typeorm.mdpackages/docs/guide/recipes/frontend.mdpackages/docs/guide/relations.mdpackages/docs/guide/sort.mdpackages/docs/packages/sql.mdpackages/docs/packages/typeorm.md
🚧 Files skipped from review as they are similar to previous changes (13)
- packages/docs/guide/pagination.md
- packages/docs/guide/recipes/express-typeorm.md
- packages/docs/guide/quick-start.md
- packages/docs/guide/sort.md
- packages/docs/guide/index.md
- packages/docs/guide/building-queries.md
- packages/docs/packages/typeorm.md
- packages/docs/guide/recipes/frontend.md
- packages/docs/guide/relations.md
- packages/docs/guide/errors.md
- packages/docs/guide/fields.md
- README.md
- packages/docs/guide/filters.md
This was referenced Jul 23, 2026
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
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.
What
Complete redesign of the docs site (rapiq.tada5hi.net), restructured after the patterns used by the Vue / Vitest / Nuxt docs: motivation first, fast quick start, essentials ordered by the user journey, deep topics later, recipes for real tasks, and per-package reference split out of the guide.
New structure
Guide (
/guide/)ErrorCodetables + HTTP mapping), The Query AST (visitors,ResolutionScope)Packages (
/packages/) — one reference page per@rapiq/*package (incl. a new@rapiq/corepage; the combined URL codec page is split per package), plus an overview with a "which packages do I need?" decision guide and a dependency-layer figure.Illustrations
ASCII diagrams are replaced with theme-aware Vue components (registered globally, styled via the existing
--rq-*tokens, responsive, light/dark):QueryPipeline— caller → wire → receiver flow on the guide landing pageQueryHub— producers → Query → consumers on Core ConceptsPackageLayers— dependency bands on the package overviewCompatibility
/integrations/*,/getting-started/*,/guide/{build,merge,schema,query,migration}) keep working via meta-refresh redirect stubs — published npm package READMEs link to them.@rapiq/memory.Verification
npm run build --workspace=packages/docspasses (VitePress dead-link check enabled by default).<meta http-equiv="refresh">tags; the three figures SSR into their pages.Summary by CodeRabbit
/guide/and/packages/routes.