Getting started
relvista renders DBML, the open-source schema language by
Holistics that dbdiagram.io uses,
as interactive entity-relationship diagrams. The Docusaurus plugin turns every ```dbml code fence
into a diagram and adds a <DbmlDiagram> component for .dbml files.
It only adds diagrams. Your theme, colours, fonts, navbar and custom CSS stay exactly as they are: the plugin does not replace the classic theme, and its styles apply only to the diagrams themselves. Diagrams follow your site's light and dark mode.
Just want to draw or edit a schema? Use the editor in your browser: no install, and your files stay on your disk. This page is about adding diagrams to a Docusaurus site.
Requirements
- Docusaurus 3.6 or later with the classic theme or preset (tested with 3.6 and 3.10)
- React 18 or 19 (Docusaurus supports React 19 from 3.7)
- Node 20 or later
Install
- npm
- Yarn
- pnpm
npm install @relvista/docusaurus-plugin
yarn add @relvista/docusaurus-plugin
pnpm add @relvista/docusaurus-plugin
Configure
Add the plugin to docusaurus.config.ts:
import type { Config } from '@docusaurus/types';
const config: Config = {
// ...
plugins: ['@relvista/docusaurus-plugin'],
themeConfig: {
// Optional: defaults for every diagram on the site.
dbml: {
height: 480, // px, or any CSS length such as '60vh'
detailLevel: 'all', // 'all' | 'keys' | 'names'
toolbar: ['view', 'search', 'detail', 'zoom', 'fit', 'fullscreen', 'export', 'print', 'link'],
palette: 'site', // 'site' | 'relvista'
},
},
};
export default config;
themeConfig.dbml | Default | Meaning |
|---|---|---|
height | 480 | Height of each diagram. A number is pixels; a string is any CSS length. |
detailLevel | 'all' | all columns, keys only (primary and foreign keys, unique columns), or table names only. |
toolbar | every button | Toolbar buttons in order: view, search, detail, zoom, fit, fullscreen, export, print, link, open-in-editor (toolbar). |
editorUrl | hosted editor | Base URL of the relvista editor for the "Open in editor" button; false hides it. |
palette | 'site' | site: diagrams take your site's Infima colours and fonts; relvista: relvista's own palette (see Colours). |
ssr | true | Draw each diagram as a static SVG at build time, shown before (and without) JavaScript (see Usage). |
The one plugin option, highlight (default true), adds DBML syntax highlighting for
```dbml static blocks and the Source tab: plugins: [['@relvista/docusaurus-plugin', { highlight: false }]].
Without preset-classic
With @docusaurus/preset-classic (the default for new sites) the line above is all you need. If
your site lists @docusaurus/theme-classic in themes instead of using the preset, register
relvista in themes too, after the classic theme, so that its MDX code wrapper (MDXComponents/Code) loads last:
themes: ['@docusaurus/theme-classic', '@relvista/docusaurus-plugin'],
Registered under plugins in that setup, ```dbml fences would stay code blocks; the build
prints a [relvista] warning when it detects this.
Your first diagram
Write a fenced code block with the language dbml in any Markdown or MDX page:
```dbml
Table users {
id integer [pk]
email varchar [unique]
}
Table posts {
id integer [pk]
author_id integer [ref: > users.id]
title varchar
}
```
It renders as:
Drag the tables, scroll to zoom, hover a table to trace its relationships and click it for details. The toolbar searches the diagram, changes the detail level, exports it (SVG, PNG, PDF), copies a link to it, and Open in editor opens it in the editor.
TypeScript
To import .dbml files, @theme/DbmlDiagram and @theme/DbmlDiff with types, add the plugin's client types to your
site's tsconfig.json:
{
"extends": "@docusaurus/tsconfig",
"compilerOptions": {
"types": ["@docusaurus/module-type-aliases", "@relvista/docusaurus-plugin/client"]
}
}
Next: all the ways to use it, diagram views and schema diffs.