Skip to content

docs: improve docs site onboarding#1172

Merged
chhoumann merged 5 commits intomasterfrom
docs/site-ia-refresh
Apr 24, 2026
Merged

docs: improve docs site onboarding#1172
chhoumann merged 5 commits intomasterfrom
docs/site-ia-refresh

Conversation

@chhoumann
Copy link
Copy Markdown
Owner

@chhoumann chhoumann commented Apr 23, 2026

Refresh the docs site onboarding and navigation so new users can choose the right QuickAdd workflow faster.

This adds decision-oriented entry points for getting started, examples, scripting, and the API; adds a Canvas capture walkthrough; and updates the landing page with a compact product workflow preview instead of a mostly abstract hero. The stable 2.12.0 docs snapshot is updated where needed so the default /docs/ version resolves the new overview links.

Navigation cleanup removes emoji-heavy docs/sidebar labels, fixes the top-nav active-state behavior, disables the unused blog plugin, and turns off blog indexing in local search to avoid the missing blogDir warning.

Verified locally with bun run typecheck, bun run build, and in-app browser checks for /, /docs/, /docs/Examples/, and /docs/Advanced/APIOverview. The build still reports the existing stale Browserslist/caniuse-lite warning.

Summary by CodeRabbit

  • Documentation

    • Added API Overview and Scripting Overview, new Examples landing, Canvas Capture walkthrough, template/dashboard examples, reorganized Getting Started into Install → Choose → First workflow, plus tip callouts and cleaned doc labels/navigation.
  • New Features

    • Homepage now shows a visual workflow preview, updated hero copy, and a “Browse examples” link.
  • Style

    • Tighter hero spacing and new responsive workflow-preview styling.

@vercel
Copy link
Copy Markdown

vercel Bot commented Apr 23, 2026

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

Project Deployment Actions Updated (UTC)
quickadd Ready Ready Preview Apr 24, 2026 5:40am

@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented Apr 23, 2026

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 997b5a60-03ca-4598-9bcf-feb45d506411

📥 Commits

Reviewing files that changed from the base of the PR and between fa370bf and d541ede.

📒 Files selected for processing (1)
  • docs/src/components/VersionAwareDocNavbarItem.tsx
🚧 Files skipped from review as they are similar to previous changes (1)
  • docs/src/components/VersionAwareDocNavbarItem.tsx

📝 Walkthrough

Walkthrough

Adds and reorganizes documentation and site navigation: new API Overview and Scripting Overview pages, Canvas capture example and Examples index, reworks Getting Started/landing content, updates sidebars/navbar to use a version-aware item, disables the blog, and adjusts landing-page styling and a WorkflowPreview component.

Changes

Cohort / File(s) Summary
Advanced docs: API & Scripting
docs/docs/Advanced/APIOverview.md, docs/versioned_docs/version-2.12.0/Advanced/APIOverview.md, docs/docs/Advanced/ScriptingGuide.md, docs/versioned_docs/version-2.12.0/Advanced/ScriptingGuide.md
Adds API Overview and Scripting Overview docs describing API access patterns, scripting module shape, example macros, variable reuse, cancellation behavior, and debugging tips.
Examples: Canvas & Index
docs/docs/Examples/Capture_CanvasCapture.md, docs/versioned_docs/version-2.12.0/Examples/Capture_CanvasCapture.md, docs/docs/Examples/index.md, docs/versioned_docs/version-2.12.0/Examples/index.md
New Canvas capture walkthrough and Examples landing page listing workflows, supported targets/write positions, behaviors, troubleshooting, and goal-based example picks.
Examples: Templates
docs/versioned_docs/version-2.12.0/Examples/Template_CreateMOCNoteWithLinkDashboard.md
Adds a versioned example demonstrating a template + .base dashboard pattern for creating a MOC with a live link dashboard.
Docs: Getting Started & Cross-links
docs/docs/index.md, docs/versioned_docs/version-2.12.0/index.md, docs/docs/QuickAddAPI.md, docs/versioned_docs/version-2.12.0/QuickAddAPI.md, docs/docs/UserScripts.md, docs/versioned_docs/version-2.12.0/UserScripts.md, docs/docs/Choices/CaptureChoice.md, docs/versioned_docs/version-2.12.0/Choices/CaptureChoice.md
Reorganizes Getting Started into a guided flow (install, choose type, first workflow), adds tip callouts linking to new API/Scripting docs, and updates Canvas capture links/formatting.
Site config & navigation
docs/docusaurus.config.js, docs/sidebars.js, docs/versioned_sidebars/version-2.12.0-sidebars.json
Disables blog, replaces navbar doc items with a custom version-aware type, removes emoji from labels, and adds new docs to sidebars and versioned sidebars.
Site components & theme mapping
docs/src/components/VersionAwareDocNavbarItem.tsx, docs/src/theme/NavbarItem/ComponentTypes.tsx
Introduces VersionAwareDocNavbarItem and registers it as custom-versionAwareDoc for version-aware navbar routing; returns null if referenced doc cannot be resolved.
Landing page UI & styles
docs/src/pages/index.tsx, docs/src/pages/index.module.css, docs/src/css/custom.css
Adds a WorkflowPreview component and dataset-driven preview, adjusts hero spacing/scales and responsive preview grid, tweaks CTA links, and removes forced active menu font-weight.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

Suggested labels

released

Poem

🐰 New pages hop out beneath the sun,
API maps and scripts for everyone,
Canvas cards collect ideas in a row,
Examples sprout where curious readers go,
Hooray — docs bloom bright, let's nibble on that fun! 🥕✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 20.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title 'docs: improve docs site onboarding' directly and clearly summarizes the main objective of the pull request, which is to refresh the documentation site's onboarding experience and navigation to help new users.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch docs/site-ia-refresh

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

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

@cloudflare-workers-and-pages
Copy link
Copy Markdown

cloudflare-workers-and-pages Bot commented Apr 23, 2026

Deploying quickadd with  Cloudflare Pages  Cloudflare Pages

Latest commit: d541ede
Status: ✅  Deploy successful!
Preview URL: https://984b632e.quickadd.pages.dev
Branch Preview URL: https://docs-site-ia-refresh.quickadd.pages.dev

View logs

@chhoumann chhoumann marked this pull request as ready for review April 23, 2026 20:42
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (2)
docs/sidebars.js (1)

105-156: Sidebar additions line up with the new pages (Examples/index, Examples/Capture_CanvasCapture, Advanced/APIOverview, Advanced/ScriptingGuide) and the label de-emoji pass is consistent across sections.

Optional refactor: consider promoting the Examples category to use link: { type: 'doc', id: 'Examples/index' } instead of listing Examples/index as the first child. That way, clicking the category header navigates to the overview (matching the navbar's /docs/Examples/ target) without an extra "Examples Overview" entry in the list. Non-blocking — current structure works fine.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/sidebars.js` around lines 105 - 156, The sidebar currently lists
"Examples/index" as a child doc and also has the Examples category header which
should navigate to the overview; change the Examples category to use link: {
type: 'doc', id: 'Examples/index' } on the category object (replace the explicit
child doc "Examples/index" and remove the "Examples Overview" child entry) so
clicking the category header opens the Examples overview (matching the navbar
`/docs/Examples/`), and ensure similar approach for any other overview
categories like the Advanced category using "Advanced/APIOverview" or
"Advanced/ScriptingGuide" if desired.
docs/src/pages/index.module.css (1)

187-191: Inconsistent first-item selectors.

.previewChoice:first-of-type and .previewResult:first-child target semantically the same "first item" but use different pseudo-classes. Since both lists are homogeneous <div> children with no siblings of other element types in the provided JSX, :first-child is simpler and consistent for both. Consider aligning them.

Proposed tweak
-.previewChoice:first-of-type,
-.previewResult:first-child {
+.previewChoice:first-child,
+.previewResult:first-child {
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/src/pages/index.module.css` around lines 187 - 191, The selectors use
inconsistent pseudo-classes: `.previewChoice:first-of-type` vs
`.previewResult:first-child`; change `.previewChoice:first-of-type` to use
`:first-child` so both rules consistently target the same semantic "first item"
behavior (update the selector referencing `.previewChoice` to
`.previewChoice:first-child` and keep the existing `.previewResult:first-child`
rule).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@docs/sidebars.js`:
- Around line 105-156: The sidebar currently lists "Examples/index" as a child
doc and also has the Examples category header which should navigate to the
overview; change the Examples category to use link: { type: 'doc', id:
'Examples/index' } on the category object (replace the explicit child doc
"Examples/index" and remove the "Examples Overview" child entry) so clicking the
category header opens the Examples overview (matching the navbar
`/docs/Examples/`), and ensure similar approach for any other overview
categories like the Advanced category using "Advanced/APIOverview" or
"Advanced/ScriptingGuide" if desired.

In `@docs/src/pages/index.module.css`:
- Around line 187-191: The selectors use inconsistent pseudo-classes:
`.previewChoice:first-of-type` vs `.previewResult:first-child`; change
`.previewChoice:first-of-type` to use `:first-child` so both rules consistently
target the same semantic "first item" behavior (update the selector referencing
`.previewChoice` to `.previewChoice:first-child` and keep the existing
`.previewResult:first-child` rule).

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 560e36ce-92e3-4194-a14c-025244cd235f

📥 Commits

Reviewing files that changed from the base of the PR and between 7dcc8e1 and a85c7a4.

⛔ Files ignored due to path filters (1)
  • docs/versioned_docs/version-2.12.0/Images/template_moc_link_dashboard_demo.png is excluded by !**/*.png
📒 Files selected for processing (23)
  • docs/docs/Advanced/APIOverview.md
  • docs/docs/Advanced/ScriptingGuide.md
  • docs/docs/Choices/CaptureChoice.md
  • docs/docs/Examples/Capture_CanvasCapture.md
  • docs/docs/Examples/index.md
  • docs/docs/QuickAddAPI.md
  • docs/docs/UserScripts.md
  • docs/docs/index.md
  • docs/docusaurus.config.js
  • docs/sidebars.js
  • docs/src/css/custom.css
  • docs/src/pages/index.module.css
  • docs/src/pages/index.tsx
  • docs/versioned_docs/version-2.12.0/Advanced/APIOverview.md
  • docs/versioned_docs/version-2.12.0/Advanced/ScriptingGuide.md
  • docs/versioned_docs/version-2.12.0/Choices/CaptureChoice.md
  • docs/versioned_docs/version-2.12.0/Examples/Capture_CanvasCapture.md
  • docs/versioned_docs/version-2.12.0/Examples/Template_CreateMOCNoteWithLinkDashboard.md
  • docs/versioned_docs/version-2.12.0/Examples/index.md
  • docs/versioned_docs/version-2.12.0/QuickAddAPI.md
  • docs/versioned_docs/version-2.12.0/UserScripts.md
  • docs/versioned_docs/version-2.12.0/index.md
  • docs/versioned_sidebars/version-2.12.0-sidebars.json
💤 Files with no reviewable changes (1)
  • docs/src/css/custom.css

devin-ai-integration[bot]

This comment was marked as resolved.

chatgpt-codex-connector[bot]

This comment was marked as resolved.

coderabbitai[bot]

This comment was marked as resolved.

coderabbitai[bot]

This comment was marked as resolved.

Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (2)
docs/src/pages/index.module.css (2)

188-192: Consider a modifier class for the highlighted preview row.

.previewChoice:nth-child(2) works today because .previewSidebarTitle is the first child and the highlight lands on the first workflow row. If the sidebar markup ever changes (extra header, reordering, conditional element), the highlight silently jumps to the wrong row. A dedicated modifier class (e.g. previewChoiceActive) applied from index.tsx to workflowRows[0] would be more resilient and self-documenting. Same applies to relying on .previewResult:first-child, though that one is less fragile since results have no preceding sibling today.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/src/pages/index.module.css` around lines 188 - 192, The CSS rule using
.previewChoice:nth-child(2) and .previewResult:first-child is fragile; introduce
a dedicated modifier class (e.g. .previewChoiceActive) and replace the
nth-child/:first-child selectors with that modifier in
docs/src/pages/index.module.css, then update the React/TSX that renders the rows
(index.tsx) to add/remove previewChoiceActive on the appropriate element (e.g.
apply it to workflowRows[0] or the component that renders each workflow row) so
the highlighted preview is driven by explicit state rather than DOM position.

137-141: Minor: min-height: 250px applies on mobile too.

When the grid collapses to a single column at max-width: 767px, the 250px min-height is applied to the whole stacked column, which only constrains the first section visually and can leave a sparse sidebar. Consider resetting min-height (or scoping it to the min-width ≥768px case) inside the mobile media query.

♻️ Suggested tweak
 `@media` (max-width: 767px) {
   .workflowPreview {
     margin-top: 1.5rem;
   }

   .previewGrid {
     grid-template-columns: 1fr;
+    min-height: 0;
   }
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/src/pages/index.module.css` around lines 137 - 141, The .previewGrid
rule currently sets min-height: 250px which also applies on mobile; update the
CSS so min-height is only active for viewports ≥768px (e.g., move the min-height
declaration into a media query for min-width: 768px) or explicitly reset
min-height: initial/auto inside the existing max-width: 767px mobile media query
to avoid the stacked single-column layout keeping the 250px constraint.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@docs/src/pages/index.module.css`:
- Around line 188-192: The CSS rule using .previewChoice:nth-child(2) and
.previewResult:first-child is fragile; introduce a dedicated modifier class
(e.g. .previewChoiceActive) and replace the nth-child/:first-child selectors
with that modifier in docs/src/pages/index.module.css, then update the React/TSX
that renders the rows (index.tsx) to add/remove previewChoiceActive on the
appropriate element (e.g. apply it to workflowRows[0] or the component that
renders each workflow row) so the highlighted preview is driven by explicit
state rather than DOM position.
- Around line 137-141: The .previewGrid rule currently sets min-height: 250px
which also applies on mobile; update the CSS so min-height is only active for
viewports ≥768px (e.g., move the min-height declaration into a media query for
min-width: 768px) or explicitly reset min-height: initial/auto inside the
existing max-width: 767px mobile media query to avoid the stacked single-column
layout keeping the 250px constraint.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: ebdc51fe-2b75-4ff3-a6f1-fc9033f8f2b8

📥 Commits

Reviewing files that changed from the base of the PR and between a1712f7 and fa370bf.

📒 Files selected for processing (2)
  • docs/docusaurus.config.js
  • docs/src/pages/index.module.css
🚧 Files skipped from review as they are similar to previous changes (1)
  • docs/docusaurus.config.js

@chhoumann chhoumann merged commit 9fd4510 into master Apr 24, 2026
5 checks passed
@chhoumann chhoumann deleted the docs/site-ia-refresh branch April 24, 2026 15:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant