ERD Markdown

VSCode extension — Interactive ER diagram editor backed by plain .ermd files.

The complete bookstore schema in light mode — crow's foot relations, key icons, status tints, and the full toolbar visible.

Overview

ERD Markdown lets you design and maintain ER diagrams entirely inside VSCode.
The diagram is stored in a .ermd file (with er-diagram: true in the front matter), so it is human-readable, diffable, and version-control friendly — no proprietary binary format, no separate toolchain.

The same schema in dark mode. Toggle with the ☀/🌙 button in the toolbar.

Features

Canvas & Navigation

Tables & Columns

Edit Table panel

Double-click any table to open the full edit panel — rename, set status, pick header color, manage columns, add design notes, and edit seed data all in one place.

Implementation status — planned & proposed

Tables and columns can be marked planned (blue tint, dashed border) or proposed (amber tint, dashed border). The Planned / Proposed filter in the toolbar dims everything else so you can focus on what is still to be built — even individual columns inside an otherwise implemented table.

Relations

Edit Relation panel

Click any relation line to open the edit panel — adjust cardinality on both ends, switch between identifying and non-identifying, bind to specific columns, toggle the FK constraint and name it, and add a comment.

Column Type Dictionary

Define reusable column types once and apply them everywhere. Built-in presets (ID, Name, Email, Flag, Timestamp …) are included; add your own with the inline form.

Annotations

Regions and comments

Use region boxes to group related tables visually and text comments to annotate any area of the canvas. Both support full style customization via the 🎨 picker.

Import & Export

Getting started

Install

Search for "ERD Markdown" in the VSCode Extensions panel and click Install.

Build from source

git clone https://github.com/PabloGonzalezMartin/ERD-markdown.git
cd ERD-markdown
npm install
cd webview && npm install && cd ..
npm run build

Press F5 in VSCode to launch the Extension Development Host.

Open a diagram

1. Create a .ermd file with the following front matter (or import examples/crowfoot-bookstore-example.csv):

---
er-diagram: true
version: 1
---

# My ER Diagram

2. Click the ⊹ icon in the editor title bar, or right-click the file → Open as ER Diagram.

Usage

Toolbar overview

The toolbar groups controls into pill sections:

Sidebar overview

The left sidebar provides icon buttons grouped by function:

Add and edit tables

Click Add Table in the sidebar. Double-click any table to open the Table Edit Panel.

• Set logical name, physical name, comment and design note
• Choose an implementation status: ✓ Implemented / … Planned / ? Proposed
• Set header color with color swatches or a color picker
• Add columns with + Add Column

Changing a table's status automatically propagates to all its columns.

Column status and reordering

Each column row in the edit panel has:

• A status cycle button (✓ → … → ?) to set implemented / planned / proposed
• A drag handle on the left — drag to reorder; an animated blue line shows where the column will land

Implementation status — visual guide

Regions and comments

Regions — click Add Region in the sidebar. When selected:

• 🎨 button opens the style picker (font size, font family, text color, border color, background)
• ✕ button deletes the region
• Resize by dragging any edge or corner handle

Comments — click Add Comment in the sidebar. When selected:

• Same 🎨 / ✕ toolbar as regions
• Double-click to edit the text inline

The style picker stays open while you pick colors and fonts — it closes only when you click outside it.

Relations

Drag from the ◉ handle on a source column to a target column to create a relation.
Click the relation line to open the Relation Edit Panel:

• From / To cardinality — 0..1, 1, 0..*, 1..*
• Line style — identifying (solid) or non-identifying (dashed)
• From / To columns — refine which columns are linked
• FK constraint — toggle and name the constraint
• Comment — click the note icon on the line to read/hide

Clicking a relation also centers the view on the two connected tables, leaving space for the edit panel on the right.

Key icons in table rows:

Search and focus

Type in the Search box to filter:

• Tables whose name matches → header highlighted, all column rows dimmed
• Tables with column name matches → matching column rows highlighted, others dimmed
• Relation lines → fade to near-invisible while a search is active

Use the Planned / Proposed filter pills to focus in-progress work — tables and columns that don't match are faded to 20% opacity.

Unified CSV import

Click Import CSV (DATA section in sidebar).

The single CSV format covers everything — tables, columns, relations, comments, design notes and status:

tableLogicalName,tablePhysicalName,tableComment,columnLogicalName,columnPhysicalName,
dictionaryName,dbType,length,notNull,isPrimaryKey,isNullable,defaultValue,columnComment,
columnDesignNote,tableDesignNote,relFromTable,relFromColumn,relToTable,relToColumn,
relCardinality,relIdentifying,relHasFk,relConstraint,relComment

• Table+column rows — fill the table and column fields; leave rel* columns blank
• Relation rows — fill only rel* columns; leave all table/column fields blank
• relIdentifying: true → solid identifying line; false → dashed non-identifying line
• tableDesignNote / columnDesignNote → sets design notes visible in the edit panel

Built-in type presets (usable as dictionaryName):

A worked example with crow's foot notation, planned/proposed tables, design notes, and relations is in examples/crowfoot-bookstore-example.csv.
A reusable AI prompt to generate CSVs for any domain is in docs/prompts/prompt-csv-generator.md.

Schema versioning

Click Save Version (sidebar → SAVE). A name prompt opens — enter e.g. v1.0 or before-refactor.
Click View Versions to list saved snapshots — each row shows name, date, table count, relation count, and a Delete button.

To generate diff DDL: Export DDL → select Version Diff → choose From and To versions.

Export DDL

Click Export DDL in the toolbar. Options in the modal:

Keyboard shortcuts

File format

The diagram is stored in a .ermd file using YAML front matter and ermd-* fenced blocks:

---
er-diagram: true
version: 1
---

# EC Site

## Dictionary

```ermd-dictionary
- id: dict_id
  name: ID
  dbType: INT
  length: null
  notNull: true
  comment: ""
```

## Tables

```ermd-table
id: tbl_user
logicalName: User
physicalName: users
comment: "Registered users"
status: implemented
columns:
  - id: col_u1
    logicalName: User ID
    physicalName: user_id
    dictionaryId: dict_id
    isPrimaryKey: true
    isNullable: false
    defaultValue: null
    comment: ""
    status: implemented
```

## Relations

```ermd-relations
- id: rel_1
  fromTableId: tbl_user
  fromColumnId: col_u1
  toTableId: tbl_order
  toColumnId: col_o2
  fromCardinality: EXACTLY_ONE
  toCardinality: ZERO_OR_MANY
  identifying: true
  hasForeignKey: true
  constraintName: fk_orders_user_id
  comment: "A user can place many orders"
```

## Layout

```ermd-layout
nameMode: logical
tables:
  - tableId: tbl_user
    x: 60
    y: 60
    width: 260
viewport:
  x: 0
  y: 0
  zoom: 1
regions: []
```

License

MIT — see LICENSE

For contributors

See CLAUDE.md for architecture notes, build commands, and PR checklist.