Switching from GitBook to Pathfinder

GitBook is a great docs platform with solid AI search features. Pathfinder is something different: a self-hosted knowledge server that indexes more than just published pages. This guide walks you through the switch in about 15 minutes.

Why Migrate

Index more than docs. GitBook indexes your published documentation. Pathfinder indexes docs, Slack threads, Discord forums, Notion pages, and code — your agents search everything your team knows, not just what's published.
Self-hosted — your data stays yours. No vendor lock-in, no per-seat pricing, no surprise deprecations. Your content lives in your repo, your search runs on your Postgres.
Both retrieval paradigms. GitBook offers AI search. Pathfinder composes both RAG search and filesystem exploration — agents pick the right tool for each sub-task.
Config-driven. One YAML file defines your sources, tools, and indexing behavior. No SaaS dashboard to click through.
Zero-infra option. Start with bash-only tools (no database, no API keys) and add RAG when you're ready. GitBook always requires their hosted platform.

What You Gain

🔍

Beyond Just Docs

GitBook indexes your docs. Pathfinder indexes your docs, Notion wikis, Slack threads, and Discord forums — all in one server. Your agents search everything your team knows.

🧭

Session State

Agents cd into directories and stay there across commands. No more repeating full paths every tool call.

⚡

Vector Grep

When grep misses, Pathfinder suggests qmd — a semantic search command that finds docs by meaning, not just text matches.

📝

Writable Workspace

Agents save notes, grep results, and intermediate files to /workspace/ during a session.

🔗

Cross-Source Related

Run related /docs/auth.md to discover semantically similar files across all sources.

🚀

Zero-Infra Start

Bash-only mode needs no database or API keys. Add RAG later with a config change — no code edits.

Concept Mapping

How GitBook concepts translate to Pathfinder:

GitBook	Pathfinder	Notes
Space	Source (type: markdown/html)	One source per content collection
AI Search	Search tool (type: search)	pgvector instead of GitBook's built-in
GitBook Assistant	Knowledge tool + Search tool	Compose multiple tools for richer retrieval
Git Sync	Webhook auto-reindex	GitHub push triggers targeted reindex
Connections (Slack/Discord)	Slack/Discord data providers	Native indexing, not just surface connections
Adaptive Content	Not available	Pathfinder serves raw knowledge, not rendered pages
Hosted platform	Self-hosted (Docker/Railway)	You own the infrastructure

Migration Walkthrough

Install Pathfinder

$ npx @copilotkit/pathfinder init

This scaffolds a pathfinder.yaml config file and a .env template in your project.

Export your GitBook content

If you have Git Sync enabled, your content is already in a repo. Clone it:

$ git clone https://github.com/your-org/your-gitbook-repo.git gitbook-docs

If you don't use Git Sync, enable it in your GitBook space settings and sync to a GitHub repo. GitBook exports your pages as Markdown files.

Configure sources

Point Pathfinder at your exported content in pathfinder.yaml:

sources:
  - name: docs
    type: markdown
    repo: https://github.com/your-org/your-gitbook-repo.git
    path: ./
    file_patterns: ["**/*.md"]
    chunk:
      target_tokens: 600
      overlap_tokens: 50

Adjust path if your docs live in a subdirectory.

Add tools

Define how agents access your knowledge:

tools:
  # Semantic search — replaces GitBook AI Search
  - name: search-docs
    type: search
    source: docs
    default_limit: 5

  # Filesystem exploration — browse docs like a directory
  - name: explore-docs
    type: bash
    sources: [docs]
    bash:
      session_state: true
      grep_strategy: hybrid

Start serving

$ npx @copilotkit/pathfinder serve

The first boot indexes your sources automatically. If you're using RAG search tools, make sure OPENAI_API_KEY and DATABASE_URL are set in your .env.

Connect your agent

Point your agent's MCP config at Pathfinder:

{
  "mcpServers": {
    "docs": { "url": "http://localhost:3001/mcp" }
  }
}

Your agent now has access to both search and filesystem tools.

Add Slack, Discord, or Notion sources (optional)

Unlike GitBook's Connections feature, Pathfinder natively indexes these sources — not just links to them:

sources:
  # ... your docs source above ...

  - name: community
    type: discord
    guild_id: "123456789"
    channels:
      - id: "111111111"
        type: forum

  - name: team-knowledge
    type: slack
    channels: ["C0123456789", "C0456789012"]

  - name: wiki
    type: notion
    root_pages: ["abc123..."]

Your agents can then search across docs, community discussions, team Slack threads, and Notion pages — all from one server.

What's Different

Pathfinder is not a drop-in replacement for GitBook's full platform. Here's what it doesn't do:

No hosted docs site

Pathfinder is an MCP server, not a documentation hosting platform. Your rendered docs site stays wherever it is — GitBook, Docusaurus, Mintlify, etc.

No adaptive content or personalization

GitBook can tailor content per visitor segment. Pathfinder serves raw knowledge to agents — it doesn't render or personalize pages.

No WYSIWYG editor

GitBook's browser-based editor is a key feature. Pathfinder reads your existing Markdown/HTML files — you edit them however you already do (VS Code, Obsidian, vim, etc.).

Analytics dashboard included

Pathfinder includes a built-in analytics dashboard at /analytics with query logging, top queries, empty result tracking, and latency metrics. Enable it with analytics.enabled: true in your config.

← Back to Pathfinder