How We Rebuilt the Prisma Docs from the Ground Up

Documentation is a key part of any software project. If your documentation isn't up to par, people won't use your library. At the same time, people are accessing documentation in new ways through agents and AI-assisted tools. Documentation should support both formats and be clear for both humans and machines.

We took on the effort to rebuild the Prisma docs without disrupting everyone's day-to-day work. This included rebuilding the site with a different documentation framework and reviewing all the content that had been in the docs for years. The new Prisma docs bring a fresh coat of paint to the whole experience and make learning about Prisma more enjoyable.

Why rebuild?

Like many open source projects, our docs had grown fast. When features shipped, docs followed quickly. That's mostly good, but over time the structure became harder to navigate and harder to trust — meaning outdated or duplicated content was easy to miss.

Duplicate content spread across pages. Related topics ended up isolated. If a community member updated one section, it was easy to miss similar content elsewhere.

The goal was simple: make the docs easier to maintain, easier to trust, and easier to improve.

Starting with the content

Before touching any code, we mapped what existed. We organized everything into four main sections:

• Getting Started
• ORM
• Prisma Postgres
• Guides

From there, we reviewed each section: removing outdated content, flattening navigation, and eliminating duplicate pages. Instead of landing on overview pages with links to subsections, we wanted users to land on a section and immediately get what they need.

We also standardized code patterns across the docs. Formatting, command examples, and section structure became consistent throughout.

Quality tooling improved in parallel. Link checks, linting, and review workflows all got tighter, making publishing safer and review cycles faster.

A new engine: Fumadocs

A big motivation for the rebuild was discovering Fumadocs, a framework built specifically for documentation. It provides:

• A content system for structured docs
• UI components out of the box
• Search and AI chat integration
• Flexible customization

When we evaluated it as a team, our old docs immediately felt dated by comparison. So we went all in: not just a framework swap, but a full redesign of the UI, colors, and fonts.

We also surfaced Search and Chat with keyboard shortcuts, Cmd-K for search and Cmd-I for chat.

Better search and chat

Search now runs on Mixedbread (an AI search provider), which uses AI models to return more accurate results based on your query, not just keyword matching.

AI Chat still uses Kapa.AI, but we replaced their default widget with a custom sidebar that persists conversations between sessions. Close the browser, come back later, and your conversation picks up where you left off.

Versioned docs

Fumadocs also let us properly version the docs for the first time. Prisma v6 has a dedicated section covering its full API. Prisma v7 stays clean and current with no version callout banners cluttering the content.

Launching without disrupting

The launch happened in stages, not all at once.

The initial work was done in a private repo. Before merging, we:

1. Disconnected automatic deploys from the old repo
2. Kept the existing site live as a static deployment
3. Merged the new structure into the main Prisma Docs repo
4. Deployed to a new host and validated everything worked

Then we went straight into monitoring: tracking every 404, watching for runtime errors, and addressing SEO issues as they surfaced.

What changed for users and contributors

For users:

• Content is easier to scan and navigate
• Paths are cleaner
• Older links are covered by redirects

For contributors:

• Clearer structure and workflow for contributors
• Stronger quality checks
• Smoother review cycles
• Less back-and-forth means updates ship faster

The biggest outcome is a lower maintenance cost for every future update.

Lessons learned

1. Start with structure. Content moves faster when navigation and URLs are stable.
2. Plan for cleanup. Migration always surfaces more to fix than expected.
3. Turn feedback into tasks quickly. Comments alone don't scale.
4. Treat launch as an operational phase. Redirects, monitoring, and communication are part of shipping.
5. Keep the momentum post-launch. That's where quality improves most.

The rebuild worked because we treated the docs as product infrastructure, not a one-time writing project. If you're planning something similar: stabilize the structure first, ship in controlled steps, and dedicate real time to post-launch stabilization.