apps/blog/content/blog/rebuilding-the-prisma-docs/index.mdx
If you haven't noticed yet, we recently rebuilt the Prisma documentation site from the ground up. It's been a massive undertaking, and we're excited to share some of the details behind it.
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.
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.
Before touching any code, we mapped what existed. We organized everything into four main sections:
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 big motivation for the rebuild was discovering Fumadocs, a framework built specifically for documentation. It provides:
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.
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.
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.
/docs/... → Prisma v7 (latest)
/docs/v6/... → Prisma v6
The launch happened in stages, not all at once.
The initial work was done in a private repo. Before merging, we:
Then we went straight into monitoring: tracking every 404, watching for runtime errors, and addressing SEO issues as they surfaced.
For users:
For contributors:
The biggest outcome is a lower maintenance cost for every future update.
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.