Docusaurus Plugin DBdiagram

A Docusaurus plugin that allows you to embed DBML database diagrams directly in your markdown files using code blocks, similar to how Mermaid works.

Installation

npm install docusaurus-plugin-dbdiagram

Configuration

Add the plugin to your docusaurus.config.js:

// docusaurus.config.mjs (ESM)
import { remarkDbdiagram } from 'docusaurus-plugin-dbdiagram';

export default {
  // ... other config
  plugins: ['docusaurus-plugin-dbdiagram'],
  presets: [
    [
      'classic',
      {
        docs: { remarkPlugins: [remarkDbdiagram] },
        blog: { remarkPlugins: [remarkDbdiagram] },
        pages: { remarkPlugins: [remarkDbdiagram] },
      },
    ],
  ],
};

Usage

Basic Usage

Simply use a dbdiagram code block in your markdown files:

# Database Schema

Here's our user management system:

```dbdiagram
Table users {
  id int [pk, increment]
  username varchar [unique, not null]
  email varchar [unique, not null]
  created_at timestamp
}

Table posts {
  id int [pk, increment]
  user_id int [ref: > users.id]
  title varchar [not null]
  content text
  created_at timestamp
}

Ref: posts.user_id > users.id
```

Advanced Usage with Options

You can also use the React component directly in MDX files for more control:

import { Dbdiagram } from 'docusaurus-plugin-dbdiagram/components';

<Dbdiagram
  theme="dark"
  height={500}
  showBranding={false}
  className="my-custom-class"
>
{`Table users {
  id int [pk, increment]
  username varchar [unique, not null]
  email varchar [unique, not null]
  created_at timestamp
}

Table posts {
  id int [pk, increment]
  user_id int [ref: > users.id]
  title varchar [not null]
  content text
  created_at timestamp
}

Ref: posts.user_id > users.id`}
</Dbdiagram>

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | theme (WIP) | 'light' \| 'dark' | 'light' | The theme for the diagram | | height | number | 400 | Height of the diagram in pixels | | showBranding (WIP) | boolean | false | Whether to show dbdiagram.io branding | | className (WIP) | string | '' | Custom CSS class for the container | | baseUrl | string | Auto-detected | Custom base URL (defaults to dbdiagram.io in both dev and production) |

Examples

E-commerce Database

```dbdiagram
Table customers {
  id int [pk, increment]
  email varchar [unique, not null]
  first_name varchar [not null]
  last_name varchar [not null]
  phone varchar
  created_at timestamp
  updated_at timestamp
}

Table products {
  id int [pk, increment]
  name varchar [not null]
  description text
  price decimal [not null]
  stock_quantity int [default: 0]
  category_id int [ref: > categories.id]
  created_at timestamp
  updated_at timestamp
}

Table categories {
  id int [pk, increment]
  name varchar [unique, not null]
  description text
  parent_id int [ref: > categories.id]
  created_at timestamp
}

Table orders {
  id int [pk, increment]
  customer_id int [ref: > customers.id]
  status varchar [default: 'pending']
  total_amount decimal [not null]
  shipping_address text [not null]
  created_at timestamp
  updated_at timestamp
}

Table order_items {
  id int [pk, increment]
  order_id int [ref: > orders.id]
  product_id int [ref: > products.id]
  quantity int [not null]
  unit_price decimal [not null]
}

Ref: products.category_id > categories.id
Ref: categories.parent_id > categories.id
Ref: orders.customer_id > customers.id
Ref: order_items.order_id > orders.id
Ref: order_items.product_id > products.id
```

Social Media Platform

```dbdiagram
Table users {
  id int [pk, increment]
  username varchar [unique, not null]
  email varchar [unique, not null]
  password_hash varchar [not null]
  profile_picture_url varchar
  bio text
  is_verified boolean [default: false]
  created_at timestamp
  updated_at timestamp
}

Table posts {
  id int [pk, increment]
  user_id int [ref: > users.id]
  content text [not null]
  image_url varchar
  likes_count int [default: 0]
  comments_count int [default: 0]
  created_at timestamp
  updated_at timestamp
}

Table comments {
  id int [pk, increment]
  post_id int [ref: > posts.id]
  user_id int [ref: > users.id]
  content text [not null]
  created_at timestamp
  updated_at timestamp
}

Table likes {
  id int [pk, increment]
  post_id int [ref: > posts.id]
  user_id int [ref: > users.id]
  created_at timestamp
}

Table follows {
  id int [pk, increment]
  follower_id int [ref: > users.id]
  following_id int [ref: > users.id]
  created_at timestamp
}

Ref: posts.user_id > users.id
Ref: comments.post_id > posts.id
Ref: comments.user_id > users.id
Ref: likes.post_id > posts.id
Ref: likes.user_id > users.id
Ref: follows.follower_id > users.id
Ref: follows.following_id > users.id
```

Development Mode

The client uses the /embed endpoint by default. You can override the base URL manually:

import { Dbdiagram } from 'docusaurus-plugin-dbdiagram/components';

<Dbdiagram
  baseUrl="https://custom-dbdiagram.example.com"
  theme="dark"
  height={600}
  border={false}
>
{`Table users {
  id int [pk, increment]
  username varchar [unique, not null]
  email varchar [unique, not null]
  created_at timestamp
}

Table posts {
  id int [pk, increment]
  user_id int
  title varchar [not null]
  content text
  created_at timestamp
}

Ref: posts.user_id > users.id`}
</Dbdiagram>

How It Works

1. Markdown Processing: The plugin uses a remark plugin to detect dbdiagram code blocks
2. Client-side Rendering: The DBML content is transformed into dbdiagram.io embed URLs
3. Iframe Embedding: Diagrams are rendered using dbdiagram.io's embed API
4. Self-contained: All DBML code is stored in your documentation, making it version-controlled and searchable

Troubleshooting

Diagram Not Rendering

1. Check that the plugin is properly installed and configured
2. Ensure your DBML syntax is valid
3. Check browser console for any JavaScript errors

Styling Issues

1. Use the className prop to add custom CSS
2. Override default styles with CSS selectors:

   .dbdiagram-container {
     border-radius: 8px;
     box-shadow: 0 2px 8px rgba(0,0,0,0.1);
   }

Contributing

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

License

MIT License - see LICENSE file for details.