Writing guides

Introduction

This guide shows you how to write guides for Prisma ORM documentation. It covers the required structure, formatting, and style conventions to ensure consistency across all guides. You'll learn about frontmatter requirements, section organization, and writing style.

Prerequisites

Before writing a guide, make sure you have:

• A clear understanding of the topic you're writing about
• Access to the Prisma documentation repository
• Familiarity with Markdown and MDX
• Knowledge of the target audience for your guide

Guide structure

Required frontmatter

Every guide must include the following frontmatter at the top of the file:

---
title: '[Descriptive title]'
description: '[One-sentence summary of what the guide covers]'
---

• title: A clear, descriptive title (e.g., "Next.js", "Multiple databases", "GitHub Actions")
• description: A one-sentence summary that describes what you'll learn or accomplish
• image: A unique header image for social media sharing (coordinate with the design team)

All frontmatter fields should use sentence case.

Required sections

1. Introduction (H2: ##)

   • Brief overview of what the guide covers
   • What the reader will learn/accomplish
   • Link to any example repositories or related resources on GitHub

2. Prerequisites (H2: ##)

   • Required software/tools with version numbers (e.g., "Node.js 20+")
   • Required accounts (e.g., "A Prisma Data Platform account")
   • Keep it concise - only list what's truly necessary

3. Main content sections (H2: ##)

   • Use numbered steps (e.g., "## 1. Set up your project", "## 2. Install and Configure Prisma")
   • Use numbered subsections (e.g., "### 2.1. Install dependencies", "### 2.2. Define your Prisma Schema")
   • Each step should build on previous steps
   • Include all commands and code snippets needed

4. Next steps (H2: ##)

   • What to do after completing the guide
   • Related guides or documentation (with links)
   • Additional resources

Writing style and voice

General principles

• Write in a clear, conversational tone
• Use active voice and present tense
• Address the reader directly using "you" (e.g., "You'll learn how to...")
• Avoid jargon and explain technical terms when necessary
• Be concise but thorough
• Guide readers step-by-step through the process

Code examples

• Include complete, runnable code examples
• Use syntax highlighting with language specification
• Include file paths in code block metadata using title=
• Use // [!code ++] to highlight added lines
• Use // [!code --] to highlight removed lines
• Use comments sparingly - only when needed to explain complex logic
• Use ```npm for package manager commands (auto-converts to pnpm/yarn/bun)
• Use ```bash for shell commands
• Use ```text for plain text files like .env
• Use ```typescript, ```prisma, ```json for respective languages

Example with file path:

import { PrismaClient } from "../generated/prisma";
import { PrismaPg } from "@prisma/adapter-pg";

const adapter = new PrismaPg({
  connectionString: process.env.DATABASE_URL!,
});

const prisma = new PrismaClient({
  adapter,
});

export default prisma;

Example showing changes:

import "dotenv/config"; 
import { defineConfig, env } from "prisma/config";

export default defineConfig({
  schema: "prisma/schema.prisma",
  migrations: {
    path: "prisma/migrations",
  },
  datasource: {
    url: env("DATABASE_URL"),
  },
});

Formatting conventions

• Use backticks for inline code:
  • File names: `schema.prisma`
  • Directory names: `prisma/`
  • Code elements: `PrismaClient`
  • Package manager commands: Use ```npm blocks (see Package manager commands)
• Use admonitions for important information:

  :::info
  Context or background information
  :::
  
  :::note
  Important details to remember
  :::
  
  :::warning
  Critical information or gotchas
  :::
  
  :::tip
  Helpful suggestions or best practices
  :::

• Use proper heading hierarchy (never skip levels)
• Use numbered sections (e.g., "## 1. Setup", "### 1.1. Install")
• Link to other documentation pages using relative paths (e.g., [Database drivers](/docs/orm/core-concepts/supported-databases/database-drivers))

Guide categories

Common patterns

Package manager commands

Use ```npm code blocks for package manager commands. These automatically convert to other package managers (pnpm, yarn, bun) in the UI:

npm install prisma --save-dev

Environment variables

Show .env file examples using ```text blocks:

DATABASE_URL="postgresql://user:password@localhost:5432/mydb"

Database provider compatibility

Include an info admonition when commands or code are PostgreSQL-specific:

:::info

If you are using a different database provider (MySQL, SQL Server, SQLite), install the corresponding driver adapter package instead of `@prisma/adapter-pg`. For more information, see [Database drivers](/docs/orm/core-concepts/supported-databases/database-drivers).

:::

Prisma Client instantiation

Show the standard pattern for creating a Prisma Client with database adapters:

import { PrismaClient } from "../generated/prisma";
import { PrismaPg } from "@prisma/adapter-pg";

const adapter = new PrismaPg({
  connectionString: process.env.DATABASE_URL!,
});

const prisma = new PrismaClient({
  adapter,
});

export default prisma;

Include a warning about connection pooling:

:::warning
We recommend using a connection pooler (like [Prisma Accelerate](https://www.prisma.io/accelerate)) to manage database connections efficiently.
:::

Best practices

1. Keep it focused

   • Each guide should cover one main topic
   • Break complex topics into multiple guides
   • Link to related guides instead of duplicating content

2. Show don't tell

   • Include practical, real-world examples
   • Provide complete, working code samples
   • Explain why certain approaches are recommended

3. Consider the context

   • Explain prerequisites clearly
   • Don't assume prior knowledge
   • Link to foundational concepts within or outside of our docs when needed

4. Maintain consistency

   • Follow the established guide structure
   • Use consistent terminology
   • Match the style of existing guides

5. Think about maintenance

   • Use version numbers where appropriate
   • Avoid time-sensitive references
   • Consider future updates when structuring content

Guide template

Use this template as a starting point for new guides. The template includes common sections and patterns used across Prisma guides.

Basic template structure

Copy this template for a new guide:

---
title: '[Your guide title]'
description: '[One-sentence summary of what you'll learn]'
image: '/img/guides/[guide-name]-cover.png'
---

## Introduction

[Brief overview of what this guide covers and what you'll accomplish. Include a link to an example repository if available.]

## Prerequisites

- [Node.js 20+](https://nodejs.org)
- [Any other prerequisites]

## 1. Set up your project

[Instructions for creating or setting up the project]

```bash
# Example command
npx create-next-app@latest my-app
cd my-app
```

## 2. Install and Configure Prisma

### 2.1. Install dependencies

To get started with Prisma, you'll need to install a few dependencies:

```npm
npm install prisma tsx @types/pg --save-dev
```

```npm
npm install @prisma/client @prisma/adapter-pg dotenv pg
```

:::info

If you are using a different database provider (MySQL, SQL Server, SQLite), install the corresponding driver adapter package instead of `@prisma/adapter-pg`. For more information, see [Database drivers](/docs/orm/core-concepts/supported-databases/database-drivers).

:::

Once installed, initialize Prisma in your project:

```bash
npx prisma init --db --output ../generated/prisma
```

:::info
You'll need to answer a few questions while setting up your Prisma Postgres database. Select the region closest to your location and a memorable name for your database.
:::

This will create:

- A `prisma` directory with a `schema.prisma` file
- A Prisma Postgres database
- A `.env` file containing the `DATABASE_URL`
- A `prisma.config.ts` file for configuration

### 2.2. Define your Prisma Schema

In the `prisma/schema.prisma` file, add your models:

```prisma title="prisma/schema.prisma"
generator client {
  provider = "prisma-client"
  output   = "../generated/prisma"
}

datasource db {
  provider = "postgresql"
}

model User { // [!code ++]
  id    Int     @id @default(autoincrement()) // [!code ++]
  email String  @unique // [!code ++]
  name  String? // [!code ++]
  posts Post[] // [!code ++]
} // [!code ++]

model Post { // [!code ++]
  id        Int     @id @default(autoincrement()) // [!code ++]
  title     String // [!code ++]
  content   String? // [!code ++]
  published Boolean @default(false) // [!code ++]
  authorId  Int // [!code ++]
  author    User    @relation(fields: [authorId], references: [id]) // [!code ++]
} // [!code ++]
```

### 2.3. Run migrations and generate Prisma Client

Create the database tables:

```bash
npx prisma migrate dev --name init
```

Then generate Prisma Client:

```bash
npx prisma generate
```

## 3. [Integration-specific steps]

[Add framework or platform-specific integration steps here]

## Next steps

Now that you've completed this guide, you can:

- [Suggestion 1]
- [Suggestion 2]
- [Related guide 1](/docs/path/to/guide)
- [Related guide 2](/docs/path/to/guide)

For more information:

- [Prisma documentation](/docs/orm)
- [Related documentation]

Adding guides to navigation

Guides are organized by category in subdirectories. To add a guide to the navigation, you need to update the appropriate meta.json file.

Main categories

The main guide categories are listed in meta.json:

{
  "title": "Guides",
  "root": true,
  "icon": "NotebookTabs",
  "pages": [
    "index",
    "frameworks",
    "deployment",
    "authentication",
    "integrations",
    "postgres",
    "database",
    "switch-to-prisma-orm",
    "upgrade-prisma-orm"
  ]
}

Adding a guide to a category

To add a guide to a category (e.g., frameworks), edit the category's meta.json file:

{
  "title": "Frameworks",
  "defaultOpen": true,
  "pages": [
    "nextjs",
    "astro",
    "nuxt",
    "your-new-guide"
  ]
}

The page name should match your .mdx filename without the extension. For example, if your file is your-new-guide.mdx, add "your-new-guide" to the pages array.

Next steps

After reading this guide, you can:

• Start writing your own guide using the provided template
• Review existing guides in the category you're contributing to
• Coordinate with the design team for a unique header image
• Submit your guide for review