Repository navigation
docs: rewrite documentation against the code, add diagrams and Cmd+B - #40
Merged
Merged
Conversation
Content - Every page rewritten and verified against convex/ and src/: real function names (listApprovedJobs, postJob, getUserProfile, updateUserName, deleteAccount, updateBookmarkStatus, ...), all six tables and indexes, roles in profiles.role (not Clerk metadata), no /admin route or middleware protection, password + email code + OAuth (no magic link), exact submission limits and rate limits, 14/30-day job lifecycle with the batched cron, bookmark/tracking rules, stable unsubscribe tokens - New pages: api-reference/email-subscriptions, technical/project-structure (was a broken sidebar link) - Deployment and contributing pages reflect the single ci.yml, deploy.yml, the skipped Vercel job, env var names per deployment, `bunx tsc --noEmit` instead of the never-exiting `bun run type-check` - Removed duplicate H1s; frontmatter title/description render the heading Diagrams - Mermaid client component (theme-aware, lazy-loaded, strict security, accessible label, collapsible source) registered for MDX - 12 diagrams: system overview, request/subscription sequence, job lifecycle, approval fan-out, sign-in sequence, authorization map, application status machine (x2), schema ER, deploy pipeline, posting flow, notification flow Interactivity - Cmd+B / Ctrl+B toggles the sidebar (collapse on desktop, drawer on mobile), ignored while typing; kbd hint in the docs toolbar - Steps/Step and Tabs/Tab registered as MDX components Tests: 7 new unit tests for the shortcut and Mermaid components.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
There was a problem hiding this comment.
Your trial has ended. Reactivate Greptile to resume code reviews.
…diagram - Sidebar collapse (Cmd+B / collapse button) now slides in and out like a dock on one easing curve, with the content grid following; Fumadocs' default morph into a floating panel is overridden. Honours prefers-reduced-motion. - Every diagram gets an "Expand" control that opens it in a native <dialog> at up to 96vw, closable by Esc, backdrop click or the close button. - System diagram switched from left-to-right to top-down so it fills the content column instead of rendering as a thin strip. - Override lodash-es to ^4.18.1: mermaid's dagre-d3-es allows the range but the resolver kept 4.17.23, which carries GHSA-r5fr-rjxr-66jc (high).
This branch was successfully deployed
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.
Summary
The audit found the docs described an app that was never built (invented profiles API, roles "synced from Clerk", middleware protecting
/admin, magic links, aproject-structurepage that didn't exist). This PR rewrites every page against the source at702d051, adds 12 Mermaid diagrams, and adds a Cmd+B sidebar toggle.Content (all 18 pages rewritten, 2 new)
convex/andsrc/.api-reference/email-subscriptions,technical/project-structure.getUserProfile,updateUserName,deleteAccount,users.currentUser,users.ensureProfile), schema (6 tables, all indexes), auth (roles only inprofiles.role, no/admin,proxy.tsprotects nothing, password + email code + OAuth), data flow (listApprovedJobs,postJob, 14/30-day lifecycle with batched cron), bookmarks ({ bookmarked, tracked }, full transition table), deployment (singleci.yml, skipped Vercel job, env var names per deployment), contributing (bunx tsc --noEmit, real checklist).Diagrams
<Mermaid>client component (src/components/docs/Mermaid.tsx): lazy-loadsmermaid@12on docs pages only,securityLevel: strict, light/dark palettes followingdata-theme,role="img"+ caption, collapsible "Diagram source". Verified in headless Chrome: 12/12 diagrams render, 0 failures.Interactivity
src/app/docs/globals.css). Hovering the left edge peeks it back in.prefers-reduced-motiondisables the transition.<dialog>at up to 96vw; Esc, backdrop click or the close button dismiss it. The system diagram is also laid out top-down so it fills the content column instead of a thin strip.⌘Bhint in the docs toolbar (shows Ctrl on non-Mac). Cmd+K search already existed; both documented on the index page.Steps/Step/Tabs/Tabregistered as MDX components (the user guide uses Steps).Also
convex/bookmarks.ts(removal is not confirm-gated).overrides.lodash-es: ^4.18.1in package.json: mermaid → dagre-d3-es allows^4.17.21but the resolver kept 4.17.23 (GHSA-r5fr-rjxr-66jc, high). The security audit job caught it.Verification
bun run lint,bunx tsc --noEmitcleanbun run test:ci104/104 (8 new), coverage 39% statementsbun run audit:depscleanbun run buildgreen, 28 static pagesmeta.jsonentry has a file, every/docs/...link resolves, no duplicate H1sFollow-ups noted by the writers (not in this PR)
admin.deleteJobdoesn't deletejobNotificationDeliveriesrows (the cron path does)tests/README.mdandconvex/README.mdare stale (npm, Supabase-era layout)