Supabase Markdown

Generate beautiful Mermaid ERD diagrams and markdown documentation from your Supabase database.types.ts file.

Features

• 📊 Mermaid ERD Diagrams - Automatically generate visual database diagrams
• 📚 Schema Documentation - Detailed markdown docs for all tables and relationships
• 🎯 Multi-Schema Support - Works with multiple schemas (business, omx, public, etc.)
• 🔄 Type-Safe - Parses TypeScript types directly from generated files
• 🚀 Zero Config - Works out of the box with Supabase CLI generated types
• 📋 Complete - Includes tables, columns, types, nullability, and relationships

Installation

npm install -D supabase-markdown

pnpm add -D supabase-markdown

yarn add -D supabase-markdown

Quick Start

1. Generate Database Types

First, generate your database.types.ts file using Supabase CLI:

# For local development
npx supabase gen types typescript --local > database.types.ts

# For production
npx supabase gen types typescript --project-id your-project-id > database.types.ts

2. Generate Documentation

# Generate to ./docs directory (default)
npx supabase-markdown

# Generate to custom directory
npx supabase-markdown --output ./documentation

# Use custom types file location
npx supabase-markdown --types-file ./src/types/database.types.ts

# Generate single combined file
npx supabase-markdown --output ./database-overview.md

3. View Your ERD

Open the generated ERD.md file in any markdown viewer that supports Mermaid diagrams (GitHub, VS Code, etc.)

Generated Files

After running the generator, you'll find:

• ERD.md - Beautiful Mermaid ERD diagram showing all tables and relationships
• database-schema.md - Detailed documentation of your database schema

Or a single combined file if you specified a .md output file.

Example Output

Mermaid ERD Diagram

erDiagram
    business_teams {
        json contact_info
        varchar created_at
        varchar id PK
        varchar name "NOT NULL"
    }
    business_campaigns {
        varchar id PK
        varchar name "NOT NULL"
        varchar team_id "NOT NULL"
        varchar status
    }
    teams ||--o{ business_campaigns : "team_id"

Loading

Schema Documentation

## Schema: `business`

### campaigns

#### Columns

| Column  | Type   | Nullable |
| ------- | ------ | -------- |
| id      | string | ✗        |
| name    | string | ✗        |
| team_id | string | ✗        |
| status  | string | ✓        |

#### Relationships

| Foreign Key            | Column(s) | References | Type        |
| ---------------------- | --------- | ---------- | ----------- |
| campaigns_team_id_fkey | team_id   | teams.id   | One-to-Many |

CLI Options

supabase-markdown [options]

Options:
  -t, --types-file <path>   Path to database.types.ts file (default: ./database.types.ts)
  -o, --output <path>       Output directory or file path (default: ./docs)
  -h, --help                Show help message

Programmatic Usage

You can also use supabase-markdown programmatically in your Node.js scripts:

import {
  parseDatabaseTypes,
  generateERDDiagram,
  generateMarkdownDocumentation,
} from 'supabase-markdown';

// Parse the database types file
const schema = parseDatabaseTypes('./database.types.ts');

// Generate ERD diagram
const erdMarkdown = generateERDDiagram(schema);

// Generate schema documentation
const schemaDoc = generateMarkdownDocumentation(schema);

// Or generate complete overview
import { generateCompleteOverview } from 'supabase-markdown';
const completeDoc = generateCompleteOverview(schema);

Workflow Integration

Development Workflow

Add to your package.json scripts:

{
  "scripts": {
    "db:types": "supabase gen types typescript --local > database.types.ts",
    "db:docs": "supabase-markdown",
    "db:update": "npm run db:types && npm run db:docs"
  }
}

CI/CD Integration

# .github/workflows/update-docs.yml
name: Update Database Documentation
on:
  push:
    paths:
      - 'supabase/migrations/**'

jobs:
  update-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npm ci
      - run: npx supabase gen types typescript --local > database.types.ts
      - run: npx supabase-markdown
      - uses: stefanzweifel/git-auto-commit-action@v4
        with:
          commit_message: 'docs: update database documentation'

How It Works

1. TypeScript Parsing: Uses the TypeScript Compiler API to parse your database.types.ts file
2. Schema Extraction: Extracts all schemas, tables, columns, and relationships from the Database type
3. Mermaid Generation: Creates Mermaid ERD syntax with proper table definitions and relationships
4. Documentation: Generates detailed markdown documentation with tables and relationship info

Multi-Schema Support

supabase-markdown automatically detects and documents all schemas in your database:

export type Database = {
  public: { ... },
  business: { ... }
}

All schemas will be included in the generated ERD and documentation.

Requirements

• Node.js 16+
• A database.types.ts file generated by Supabase CLI

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Credits

Inspired by prisma-markdown by @samchon. This project adapts the concept of generating markdown documentation and ERD diagrams for Supabase databases.

License

MIT © Brandon Ha

---

Made with ❤️ for the Supabase community