Search & Navigation

The Docs module provides full-text search and multiple navigation tools to help you find content quickly. This guide covers the search system, sidebar navigation, table of contents, page linking, and keyboard shortcuts.

Full-Text Search

How Search Works

The Docs module uses a PostgreSQL-based full-text search index that covers all pages within your tenant. Every page is indexed when it is created, and the index is updated automatically whenever the page's title or content changes.

The search index uses weighted relevance ranking:

• Title receives the highest weight (Priority A). A search term that matches in the title ranks higher than one that matches only in the body.

• Content receives standard weight. Matches anywhere in the page body are included in results.

Performing a Search

From the Docs Interface

1. Navigate to Docs from the main navigation.

2. Click the Search button or navigate to the search page.

3. Enter your search query in the search field.

4. Results appear ranked by relevance.

From the Book Workspace

While viewing a book, use the search functionality to find pages within that book and across all books.

Search Results

Each search result includes:

• Page title: The title of the matching page, with search terms highlighted.

• Snippet: A text excerpt from the page content showing the matching context, with search terms highlighted.

• Book name: The book the page belongs to.

• Chapter name: The chapter the page belongs to (if any).

• Relevance score: Results are ordered by relevance, with the best matches first.

Click a result to navigate directly to that page within its book workspace.

Search Tips

• Use specific terms. The more specific your search, the more relevant the results. "Stripe webhook configuration" will yield more targeted results than "setup".

• Title matches rank highest. If you know roughly what the page is called, search by title keywords.

• All words are matched. The search engine attempts to find results containing all your search terms. Longer queries narrow the results.

• Search scope. Search covers all pages in all books that your current user has access to (based on book visibility). Personal books belonging to other users are excluded.

JSON API

Search is also available via JSON for programmatic access:

• Send a request to the search endpoint with Accept: application/json header.

• The response includes the query, matching results (with page data and snippets), and the total count.

Sidebar Navigation

The sidebar is the primary navigation tool within a book. It displays the complete content tree: chapters with their nested pages, and top-level pages that sit outside chapters.

Tree Structure

The sidebar tree is organized as follows:

Chapter 1
  |. Page A
  |. Page B
  |. Page C
Chapter 2
  |. Page D
  |. Page E
Page F (top-level)
Page G (top-level)

• Chapters appear as collapsible groups. Click a chapter name to expand or collapse it.

• Pages appear as clickable items within their chapter. Click a page to load it in the main content area.

• Top-level pages appear in the tree outside of any chapter group.

Active Page Indicator

The currently viewed page is highlighted in the sidebar with a visual indicator (accent color background, bold text, or similar styling). This makes it easy to orient yourself within the book's structure.

Sort Order

Items in the sidebar follow their assigned sort order:

• Chapters are ordered by sort_order, then by name.

• Pages within a chapter are ordered by sort_order, then by title.

• Top-level pages follow the same ordering.

Drag-and-Drop Reordering

The sidebar supports drag-and-drop for reorganizing content:

Reorder Pages Within a Chapter

1. Click and hold a page in the sidebar.

2. Drag it above or below other pages within the same chapter.

3. Release. The new order is saved immediately.

Move a Page to a Different Chapter

1. Drag a page from one chapter into another chapter's area.

2. Release. The page's chapter assignment changes and the sort order updates.

Move a Page to Top Level

1. Drag a page out of its chapter and into the top-level area of the sidebar (outside any chapter group).

2. Release. The page's chapter is cleared and it becomes a top-level page.

Reorder Chapters

1. Drag a chapter heading above or below another chapter heading.

2. Release. All chapters receive updated sort order values.

Portal Sidebar

When portal contacts view a book, the sidebar shows the same tree structure but with these differences:

• Only published pages are shown. Draft pages are hidden.

• Chapters with no published pages are hidden entirely.

• No drag-and-drop capability (the portal is read-only).

Page Status Indicators

In the admin sidebar, pages display their status:

This helps you quickly identify which pages are live and which are still in draft.

Table of Contents

When viewing a page with multiple headings, the rendered content structure serves as an implicit table of contents. Each heading level (H1 through H4) creates a navigable section that readers can scan to find the information they need.

For long pages, consider:

• Using a clear heading hierarchy (H1 for major sections, H2 for subsections, H3 for sub-subsections).

• Starting with an overview paragraph before the first heading.

• Using descriptive heading text that conveys the section's topic.

Page Linking to Entities

Books can be linked to CRM entities (contacts, companies, and users). These links create cross-references between your documentation and your CRM data.

Adding Links

1. Open the book workspace.

2. Navigate to the book's detail or settings panel.

3. Use the entity link feature to search for and select an entity.

4. Choose the entity type:

   • Contact: Links to a CRM contact record.

   • Company: Links to a CRM company record.

   • User: Links to a team member.

How Links Appear

Linked entities are displayed in the book's detail panel:

• Contact links show the contact's name and link to their CRM record at /crm/contacts/{id}.

• Company links show the company's name and link to their CRM record at /crm/companies/{id}.

• User links show the user's name (no clickable URL, as users do not have a dedicated CRM page).

Use Cases for Entity Links

• Client onboarding books: Link the book to the client's company so team members can quickly navigate between the client's documentation and their CRM record.

• Contact-specific procedures: Link a book to a specific contact to indicate the documentation relates to that individual.

• Team training: Link a training book to the team member it was created for.

Removing Links

1. In the book's linked entities panel, find the entity.

2. Click the remove/unlink action.

3. The link is deleted. Neither the book nor the entity is otherwise affected.

Entity links are unique per book, you cannot link the same entity to the same book twice. Attempting to do so will simply return the existing link.

Keyboard Shortcuts

The Tiptap editor and the Docs interface support standard keyboard shortcuts:

Editor Shortcuts

Markdown Shortcuts in Editor

The editor supports Markdown-style shortcuts for quick formatting:

Navigation Shortcuts

Standard browser navigation shortcuts apply:

Search Index Maintenance

The full-text search index is maintained automatically:

• On page creation: The index is populated with the new page's title and content.

• On content edit: The index is updated with the revised content.

• On title change: The index is refreshed to reflect the new title (even if content did not change).

There is no manual action needed to maintain the search index. If you notice search results that seem stale, editing and re-saving the page will force an index update.

Tips for Effective Documentation

Organize for Discoverability

• Use books for broad topics (one book per product, service, or knowledge area).

• Use chapters to group related pages within a book.

• Use top-level pages for content that does not fit neatly into a chapter (e.g., an introduction or glossary).

Write for Search

• Use descriptive page titles that contain the key terms users will search for.

• Write excerpts that summarize the page content, these appear in search results and help users decide which result to click.

• Use headings liberally. They improve readability and help the search engine understand your content structure.

Use Draft Status Effectively

• Start new pages as drafts.

• Publish them only when they are reviewed and ready for the target audience.

• Use unpublish (revert to draft) when content needs significant updates.

Version History as Safety Net

• Every title and content change is versioned automatically.

• If you make a mistake, you can review the version history and restore a previous version.

• Do not hesitate to make edits, the version system ensures nothing is permanently lost.