> ## Documentation Index
> Fetch the complete documentation index at: https://docs.virtuous.org/llms.txt
> Use this file to discover all available pages before exploring further.
# Search & Navigation
> Find what you need fast — the search bar, keyboard shortcuts, table of contents, breadcrumbs, and the cross-link patterns that make the docs navigable as a connected web
The Virtuous API Docs are designed to be navigated in three complementary ways: **search** (when you know what you're looking for), **structured browsing** (when you're orienting yourself), and **cross-link following** (when you're going deeper from a topic you've already found). This page covers all three, plus the keyboard shortcuts that make navigation faster.
## The fast path: keyboard search
The fastest way to find anything in the docs:
| Action | Shortcut |
| ----------------------------- | --------------------------------------------------------------------------------------- |
| Open search | Cmd + K (macOS) or Ctrl + K (Windows/Linux) |
| Move between results | ↑ / ↓ arrows |
| Open the highlighted result | Enter |
| Close search | Esc |
| Open the AI Assistant instead | Cmd + I (macOS) or Ctrl + I (Windows/Linux) |
Search is full-text across all four tabs (CRM+, Raise, Volunteer, Virtuous). You don't need to switch tabs to find content — search ranges across the entire docs set.
## What search returns
Search ranks results by relevance. Each result shows:
* The page title
* The group and tab it belongs to
* A short preview of the matching content
| If you see... | It means |
| ---------------------------------------- | ----------------------------------------------------------------------------------- |
| Multiple results from the same group | The topic spans multiple pages within that group — typical for cross-cutting topics |
| Results from all four tabs | The topic exists in each product or applies platform-wide |
| Results from a Best Practices page | The topic has architectural treatment, not just reference treatment |
| Results from a Concepts page | Reference material — fields, resources, relationships |
| Results from a Workflows or Recipes page | Task-oriented walkthroughs — how to actually do the thing |
When you find what you need, follow the page's internal table of contents and the cross-links to get deeper context. Search is the starting point, not the destination.
## Strong searches vs. weak searches
A few patterns that improve search results:
| Weak search | Strong search |
| ------------ | ------------------------------------------------------- |
| `error` | `error recovery patterns` or `volunteer error handling` |
| `auth` | `oauth flow` or `volunteer bearer token` |
| `pagination` | `volunteer page size` or `crm skip take` |
| `users` | `volunteer user upsert` or `crm contact create` |
| `webhook` | `crm webhook signature` or `raise webhook retry` |
Two principles: **mention the product (CRM+, Raise, Volunteer)** when the topic differs across them, and **use specific terms** (the actual field name, the actual concept) rather than generic ones.
## Searching across products
If you don't specify a product, search returns matches across all four tabs. For cross-cutting topics (rate limits, error handling, pagination, security), this is useful — you can compare how each API handles the same concern.
Example searches that benefit from cross-product results:
| Search | What you'll see |
| -------------------------------- | ---------------------------------------------------------------------------------------------- |
| `pagination` | The pagination page from each of CRM+, Raise, and Volunteer — useful for comparing conventions |
| `webhook signature verification` | The verification pages from CRM+ and Raise (Volunteer doesn't have webhooks) |
| `email matching` | Patterns for matching across CRM+ Contacts and Volunteer Users |
| `incremental sync` | Approaches across all three products |
## Structured browsing
When you don't yet know what you're looking for, browse by group:
| Browsing pattern | When to use it |
| ------------------------- | ---------------------------------------------------------------------------------------------------- |
| **By tab** | You know which product you're working with (CRM+, Raise, Volunteer) and want to see what's available |
| **By group within a tab** | You know you need workflow guidance, or best practices, or webhook setup, etc. |
| **By page** | You know the specific page you want — direct navigation |
The left sidebar shows the full hierarchy for the current tab. Click between groups to expand and collapse. Use the search shortcut whenever browsing feels slower than searching.
## In-page navigation
Once you're on a page, several elements help you navigate within it and back out:
### The table of contents (right sidebar)
Every page longer than a few sections has a table of contents in the right sidebar showing the page's headings. Click any heading to jump there. As you scroll, the current section highlights.
For long pages (Best Practices, Integration Recipes), the table of contents is the fastest way to skip to the section you want.
### Anchor links
Every heading on every page has an anchor link. Hover over a heading to reveal the link icon; click to copy a direct URL.
Use anchor links to:
* Share a specific section with a teammate
* Bookmark a specific subsection you reference often
* Link to specific guidance from a partner's own internal docs
### Breadcrumbs (top of page)
The top of each page shows the path: Tab → Group → Page. Click any breadcrumb segment to go back up a level.
### Closing CardGroup (every page)
Every page closes with a `` containing four suggested next-read pages. These are curated — the most natural next pages from where you are. Follow them when you want to go deeper on the topic you just read.
## Cross-link patterns built into the docs
The docs are designed as a connected web, not a flat list. Cross-links between pages follow consistent patterns:
| Link pattern | Example |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **Workflow → Concept** | A workflow page references the Concept page for the underlying data model |
| **Recipe → Workflow** | Recipes are end-to-end implementations; they reference the workflows that make them up |
| **Recipe → Best Practice** | Recipes reference the cross-cutting patterns they depend on (error recovery, performance, etc.) |
| **Best Practice → Workflow / Recipe** | Best Practices reference specific workflows or recipes where they apply |
| **Cross-API** | Volunteer's "Combine with CRM+ Data" recipe links to CRM+'s Contact concepts, and vice versa |
| **Up to platform** | Product-specific pages link to platform-wide content in the Virtuous tab when relevant (Partners, MCP, Docs Guide) |
Following cross-links is often faster than searching — the docs already know what's related to what you're reading.
## Linking back to the docs from outside
When you want to share a specific docs section with a teammate or paste a link into your team's internal docs:
| What you want to link to | How |
| ------------------------ | ------------------------------------------------------------------ |
| A specific page | Copy the URL from your browser |
| A specific section | Hover over the heading; click the link icon to copy the anchor URL |
| The entire docs site | `https://docs.virtuous.org/` |
| A specific tab's home | Use the tab's overview page URL (e.g., `/volunteer/overview`) |
URLs are stable. Mintlify hosts the docs and Virtuous owns the domain — links you save today will work indefinitely.
## URL deep-linking
Beyond standard page URLs, a few special parameters let you deep-link into specific behaviors:
| URL pattern | What it does |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `?assistant` | Opens the page with the AI Assistant chat panel already open |
| `?assistant=` | Opens the page with the AI Assistant chat panel open and your question pre-filled (URL-encode the question — spaces become `%20`, etc.) |
Example: `https://docs.virtuous.org/volunteer/overview?assistant=How%20do%20I%20detect%20deleted%20users%3F` opens the Volunteer Overview page with the AI Assistant pre-populated with "How do I detect deleted users?"
This is useful for:
* Linking from your team's onboarding docs to "ask the assistant about X"
* Emailing a teammate a specific question pre-loaded into the assistant
* Embedding "ask about this" links in your customer-facing support content
See [AI Assistant](/virtuous/docs-guide/ai-assistant) for more on what the assistant can answer.
## Common navigation patterns
A few patterns that emerge naturally:
### "I'm new — orient me"
1. Visit [docs.virtuous.org](https://docs.virtuous.org)
2. Pick the relevant product tab (CRM+, Raise, or Volunteer)
3. Read the Overview, Quickstart, and Authentication pages in the Get Started group
4. Move to Core Concepts
### "I'm building something — show me how"
1. Search for the workflow or recipe matching your task
2. Or browse the relevant product's Workflows / Recipes groups
3. Follow the cross-links to Concepts (for reference) and Best Practices (for architectural patterns)
### "I'm reviewing my integration's quality"
1. Browse the relevant product's Best Practices group
2. Use the Decision tables at the top of each page to find what applies to you
3. Compare your implementation against documented patterns
### "I'm debugging"
1. Search for the specific error code, field name, or symptom
2. Or use the AI Assistant (Cmd+I) to describe what's happening
3. Check Error Handling, Rate Limits, and Error Recovery Patterns pages
### "I'm hunting a specific field"
1. Search for the field name directly
2. The Concepts pages have comprehensive field reference
3. Or jump to the API Playground for the relevant endpoint
## When search isn't returning what you want
A few troubleshooting tips:
| Symptom | Try |
| -------------------------------------------------------- | ------------------------------------------------------------------------ |
| Too many results, none relevant | Add the product name (CRM+, Raise, Volunteer) to the search |
| Generic results from training-data-style content | Make the search more specific to the Virtuous concept |
| Search returns nothing | Try the AI Assistant — it can phrase the question differently |
| You're looking for an enum value or specific field | Search the exact name; check the Concepts page for the relevant resource |
| You think the content should exist but you can't find it | Open the AI Assistant — it may find it where keyword search didn't |
When search and browsing both come up short, the AI Assistant is often the right next step. See [AI Assistant](/virtuous/docs-guide/ai-assistant).
## Where to go next
The in-docs AI chat — when you have a question you'd rather ask than search.
Pull docs content into your external AI tools (ChatGPT, Claude, Cursor, etc.).
Test endpoints directly in the docs and copy the resulting code into your project.
The full orientation to the docs structure — tabs, groups, and conventions.