mkdocs-dbml-plugin 1.0.0__tar.gz

mkdocs_dbml_plugin-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZhuchkaTriplesix
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mkdocs_dbml_plugin-1.0.0/MANIFEST.in

@@ -0,0 +1,10 @@
+include README.md
+include LICENSE
+include pyproject.toml
+include setup.py
+recursive-include mkdocs_dbml_plugin *.py *.pyx
+global-exclude __pycache__ *.py[cod] *.so *.pyd
+global-exclude *.c
+prune example
+prune .github
+prune tests

mkdocs_dbml_plugin-1.0.0/PKG-INFO

@@ -0,0 +1,272 @@
+Metadata-Version: 2.4
+Name: mkdocs-dbml-plugin
+Version: 1.0.0
+Summary: MkDocs plugin to render DBML as interactive ERD diagrams
+Author-email: ZhuchkaTriplesix <mrlololoshka94@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ZhuchkaTriplesix/mkdocs-dbml
+Project-URL: Documentation, https://github.com/ZhuchkaTriplesix/mkdocs-dbml#readme
+Project-URL: Repository, https://github.com/ZhuchkaTriplesix/mkdocs-dbml
+Project-URL: Issues, https://github.com/ZhuchkaTriplesix/mkdocs-dbml/issues
+Keywords: mkdocs,plugin,dbml,erd,diagram,documentation
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Documentation
+Classifier: Topic :: Text Processing :: Markup
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mkdocs>=1.0.0
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: pydbml>=1.0.0
+Provides-Extra: dev
+Requires-Dist: cython>=0.29; extra == "dev"
+Dynamic: license-file
+
+# MkDocs DBML Plugin
+
+MkDocs plugin that renders [DBML](https://dbml.dbdiagram.io/) code blocks as interactive, visual ERD (Entity-Relationship Diagram) directly in your documentation.
+
+## Features
+
+- **Interactive SVG diagrams** — drag tables, zoom with mouse wheel, pan the canvas
+- **Field-to-field connections** — relationship lines go from the exact FK field to the exact PK field
+- **Orthogonal routing** — lines use right-angle paths and automatically avoid overlapping tables
+- **Click-to-select** — click any relationship line to highlight it and its connected fields
+- **Crow's foot notation** — classic ERD markers for one-to-one, one-to-many, many-to-many
+- **Material Design 3 icons** — PK, FK, NOT NULL, UNIQUE badges on fields
+- **7 color themes** — default, ocean, sunset, forest, dark, dark_gray, black
+- **High performance** — optional Cython-compiled routing engine; Numba JIT fallback
+
+## Installation
+
+### From source (local project)
+
+```bash
+git clone https://github.com/ZhuchkaTriplesix/mkdocs-dbml.git
+cd mkdocs-dbml
+pip install -e .
+```
+
+### From source with Cython (optional, for best performance)
+
+If you have a C compiler available (MSVC on Windows, gcc/clang on Linux/macOS):
+
+```bash
+pip install cython
+python setup.py build_ext --inplace
+pip install -e .
+```
+
+Without Cython the plugin works fine — it falls back to a pure-Python router.
+
+### Dependencies
+
+Installed automatically by `pip install`:
+
+| Package | Purpose |
+|---------|---------|
+| `mkdocs >= 1.0` | Documentation framework |
+| `pydbml >= 1.0` | DBML parser |
+
+## Quick start
+
+### 1. Enable the plugin in `mkdocs.yml`
+
+```yaml
+plugins:
+  - search
+  - dbml
+```
+
+### 2. Write DBML in any Markdown file
+
+````markdown
+```dbml
+Table users {
+  id integer [primary key]
+  username varchar(50) [not null, unique]
+  email varchar(100) [not null]
+  created_at timestamp
+}
+
+Table posts {
+  id integer [primary key]
+  user_id integer [ref: > users.id]
+  title varchar(200) [not null]
+  content text
+  published boolean [default: false]
+  created_at timestamp
+}
+
+Table comments {
+  id integer [primary key]
+  post_id integer [ref: > posts.id]
+  user_id integer [ref: > users.id]
+  content text [not null]
+  created_at timestamp
+}
+```
+````
+
+### 3. Build or serve
+
+```bash
+mkdocs serve        # live preview at http://127.0.0.1:8000
+mkdocs build        # static output in site/
+```
+
+The plugin converts every `` ```dbml `` code block into an interactive SVG diagram.
+
+### Including native `.dbml` files
+
+You can embed the contents of a `.dbml` file instead of pasting DBML inline. Paths are relative to your `docs_dir`.
+
+**Option 1 — single line with path (must end with `.dbml`, no spaces):**
+
+````markdown
+```dbml
+schema.dbml
+```
+````
+
+**Option 2 — explicit `file:` or `include:` prefix:**
+
+````markdown
+```dbml
+file: schemas/public.dbml
+```
+````
+
+The file is read from `docs_dir` (e.g. `docs/schema.dbml` or `docs/schemas/public.dbml`). Path traversal (`../`) outside `docs_dir` is not allowed.
+
+## Configuration
+
+All options are set under the `dbml` plugin entry in `mkdocs.yml`:
+
+```yaml
+plugins:
+  - dbml:
+      theme: default      # color theme (see below)
+      show_indexes: true   # display index information
+      show_notes: true     # display table notes
+```
+
+### Themes
+
+| Theme | Header gradient | Best for |
+|-------|----------------|----------|
+| `default` | Purple | Light backgrounds |
+| `ocean` | Deep blue → cyan | Light backgrounds |
+| `sunset` | Pink → blue | Light backgrounds |
+| `forest` | Dark teal → green | Light backgrounds |
+| `dark` | Dark violet | Dark backgrounds |
+| `dark_gray` | Gray → slate | Dark backgrounds, neutral |
+| `black` | Near-black → gray | Dark backgrounds, high contrast |
+
+Example with the dark theme:
+
+```yaml
+plugins:
+  - dbml:
+      theme: dark
+```
+
+## DBML syntax cheat-sheet
+
+```dbml
+Table table_name {
+  column_name column_type [attributes]
+}
+```
+
+### Column attributes
+
+| Attribute | Syntax |
+|-----------|--------|
+| Primary key | `[primary key]` or `[pk]` |
+| Not null | `[not null]` |
+| Unique | `[unique]` |
+| Default value | `[default: value]` |
+| Foreign key | `[ref: > other_table.column]` |
+
+### Relationship types
+
+| Syntax | Meaning | Markers |
+|--------|---------|---------|
+| `ref: > table.col` | Many-to-one | Circle → Crow's foot |
+| `ref: < table.col` | One-to-many | Crow's foot → Bar |
+| `ref: - table.col` | One-to-one | Bar → Bar |
+| `ref: <> table.col` | Many-to-many | Crow's foot → Crow's foot |
+
+### Indexes and notes
+
+```dbml
+Table example {
+  id integer [pk]
+  user_id integer
+  post_id integer
+
+  indexes {
+    user_id
+    (user_id, post_id) [unique]
+  }
+
+  Note: 'Description of this table'
+}
+```
+
+Full DBML specification: [dbml.dbdiagram.io/docs](https://dbml.dbdiagram.io/docs/)
+
+## Interaction guide
+
+| Action | How |
+|--------|-----|
+| **Move a table** | Click and drag the table |
+| **Pan the canvas** | Click and drag empty space |
+| **Zoom** | Mouse wheel (10% – 300%) |
+| **Fullscreen** | Click the expand button (top-right), Esc to exit |
+| **Highlight connections** | Hover over a table |
+| **Select a line** | Click on any relationship line |
+| **Field tooltip** | Hover over a field row |
+
+## Project structure
+
+```
+mkdocs-dbml/
+├── setup.py                          # package config
+├── requirements.txt
+├── mkdocs_dbml_plugin/
+│   ├── __init__.py
+│   ├── plugin.py                     # MkDocs hook + interactive JS
+│   ├── renderer.py                   # DBML → SVG rendering + CSS
+│   ├── layout.py                     # BFS graph layout engine
+│   ├── config.py                     # theme definitions
+│   ├── routing.py                    # import wrapper (Cython → Python)
+│   ├── _routing.pyx                  # Cython routing (optional)
+│   └── _routing_py.py               # pure-Python routing fallback
+└── example/                          # demo MkDocs site
+    ├── mkdocs.yml
+    └── docs/
+        └── *.md
+```
+
+## Publishing to PyPI (maintainers)
+
+```bash
+pip install build twine
+python -m build
+twine upload dist/*
+```
+
+Use an API token from [pypi.org/manage/account](https://pypi.org/manage/account/) (env `TWINE_USERNAME=__token__`, `TWINE_PASSWORD=<token>`).
+
+## License
+
+MIT

mkdocs_dbml_plugin-1.0.0/README.md

@@ -0,0 +1,241 @@
+# MkDocs DBML Plugin
+
+MkDocs plugin that renders [DBML](https://dbml.dbdiagram.io/) code blocks as interactive, visual ERD (Entity-Relationship Diagram) directly in your documentation.
+
+## Features
+
+- **Interactive SVG diagrams** — drag tables, zoom with mouse wheel, pan the canvas
+- **Field-to-field connections** — relationship lines go from the exact FK field to the exact PK field
+- **Orthogonal routing** — lines use right-angle paths and automatically avoid overlapping tables
+- **Click-to-select** — click any relationship line to highlight it and its connected fields
+- **Crow's foot notation** — classic ERD markers for one-to-one, one-to-many, many-to-many
+- **Material Design 3 icons** — PK, FK, NOT NULL, UNIQUE badges on fields
+- **7 color themes** — default, ocean, sunset, forest, dark, dark_gray, black
+- **High performance** — optional Cython-compiled routing engine; Numba JIT fallback
+
+## Installation
+
+### From source (local project)
+
+```bash
+git clone https://github.com/ZhuchkaTriplesix/mkdocs-dbml.git
+cd mkdocs-dbml
+pip install -e .
+```
+
+### From source with Cython (optional, for best performance)
+
+If you have a C compiler available (MSVC on Windows, gcc/clang on Linux/macOS):
+
+```bash
+pip install cython
+python setup.py build_ext --inplace
+pip install -e .
+```
+
+Without Cython the plugin works fine — it falls back to a pure-Python router.
+
+### Dependencies
+
+Installed automatically by `pip install`:
+
+| Package | Purpose |
+|---------|---------|
+| `mkdocs >= 1.0` | Documentation framework |
+| `pydbml >= 1.0` | DBML parser |
+
+## Quick start
+
+### 1. Enable the plugin in `mkdocs.yml`
+
+```yaml
+plugins:
+  - search
+  - dbml
+```
+
+### 2. Write DBML in any Markdown file
+
+````markdown
+```dbml
+Table users {
+  id integer [primary key]
+  username varchar(50) [not null, unique]
+  email varchar(100) [not null]
+  created_at timestamp
+}
+
+Table posts {
+  id integer [primary key]
+  user_id integer [ref: > users.id]
+  title varchar(200) [not null]
+  content text
+  published boolean [default: false]
+  created_at timestamp
+}
+
+Table comments {
+  id integer [primary key]
+  post_id integer [ref: > posts.id]
+  user_id integer [ref: > users.id]
+  content text [not null]
+  created_at timestamp
+}
+```
+````
+
+### 3. Build or serve
+
+```bash
+mkdocs serve        # live preview at http://127.0.0.1:8000
+mkdocs build        # static output in site/
+```
+
+The plugin converts every `` ```dbml `` code block into an interactive SVG diagram.
+
+### Including native `.dbml` files
+
+You can embed the contents of a `.dbml` file instead of pasting DBML inline. Paths are relative to your `docs_dir`.
+
+**Option 1 — single line with path (must end with `.dbml`, no spaces):**
+
+````markdown
+```dbml
+schema.dbml
+```
+````
+
+**Option 2 — explicit `file:` or `include:` prefix:**
+
+````markdown
+```dbml
+file: schemas/public.dbml
+```
+````
+
+The file is read from `docs_dir` (e.g. `docs/schema.dbml` or `docs/schemas/public.dbml`). Path traversal (`../`) outside `docs_dir` is not allowed.
+
+## Configuration
+
+All options are set under the `dbml` plugin entry in `mkdocs.yml`:
+
+```yaml
+plugins:
+  - dbml:
+      theme: default      # color theme (see below)
+      show_indexes: true   # display index information
+      show_notes: true     # display table notes
+```
+
+### Themes
+
+| Theme | Header gradient | Best for |
+|-------|----------------|----------|
+| `default` | Purple | Light backgrounds |
+| `ocean` | Deep blue → cyan | Light backgrounds |
+| `sunset` | Pink → blue | Light backgrounds |
+| `forest` | Dark teal → green | Light backgrounds |
+| `dark` | Dark violet | Dark backgrounds |
+| `dark_gray` | Gray → slate | Dark backgrounds, neutral |
+| `black` | Near-black → gray | Dark backgrounds, high contrast |
+
+Example with the dark theme:
+
+```yaml
+plugins:
+  - dbml:
+      theme: dark
+```
+
+## DBML syntax cheat-sheet
+
+```dbml
+Table table_name {
+  column_name column_type [attributes]
+}
+```
+
+### Column attributes
+
+| Attribute | Syntax |
+|-----------|--------|
+| Primary key | `[primary key]` or `[pk]` |
+| Not null | `[not null]` |
+| Unique | `[unique]` |
+| Default value | `[default: value]` |
+| Foreign key | `[ref: > other_table.column]` |
+
+### Relationship types
+
+| Syntax | Meaning | Markers |
+|--------|---------|---------|
+| `ref: > table.col` | Many-to-one | Circle → Crow's foot |
+| `ref: < table.col` | One-to-many | Crow's foot → Bar |
+| `ref: - table.col` | One-to-one | Bar → Bar |
+| `ref: <> table.col` | Many-to-many | Crow's foot → Crow's foot |
+
+### Indexes and notes
+
+```dbml
+Table example {
+  id integer [pk]
+  user_id integer
+  post_id integer
+
+  indexes {
+    user_id
+    (user_id, post_id) [unique]
+  }
+
+  Note: 'Description of this table'
+}
+```
+
+Full DBML specification: [dbml.dbdiagram.io/docs](https://dbml.dbdiagram.io/docs/)
+
+## Interaction guide
+
+| Action | How |
+|--------|-----|
+| **Move a table** | Click and drag the table |
+| **Pan the canvas** | Click and drag empty space |
+| **Zoom** | Mouse wheel (10% – 300%) |
+| **Fullscreen** | Click the expand button (top-right), Esc to exit |
+| **Highlight connections** | Hover over a table |
+| **Select a line** | Click on any relationship line |
+| **Field tooltip** | Hover over a field row |
+
+## Project structure
+
+```
+mkdocs-dbml/
+├── setup.py                          # package config
+├── requirements.txt
+├── mkdocs_dbml_plugin/
+│   ├── __init__.py
+│   ├── plugin.py                     # MkDocs hook + interactive JS
+│   ├── renderer.py                   # DBML → SVG rendering + CSS
+│   ├── layout.py                     # BFS graph layout engine
+│   ├── config.py                     # theme definitions
+│   ├── routing.py                    # import wrapper (Cython → Python)
+│   ├── _routing.pyx                  # Cython routing (optional)
+│   └── _routing_py.py               # pure-Python routing fallback
+└── example/                          # demo MkDocs site
+    ├── mkdocs.yml
+    └── docs/
+        └── *.md
+```
+
+## Publishing to PyPI (maintainers)
+
+```bash
+pip install build twine
+python -m build
+twine upload dist/*
+```
+
+Use an API token from [pypi.org/manage/account](https://pypi.org/manage/account/) (env `TWINE_USERNAME=__token__`, `TWINE_PASSWORD=<token>`).
+
+## License
+
+MIT

mkdocs_dbml_plugin-1.0.0/mkdocs_dbml_plugin/__init__.py

@@ -0,0 +1,4 @@
+from .plugin import DbmlPlugin
+
+__version__ = "1.0.0"
+__all__ = ["DbmlPlugin"]

mkdocs_dbml_plugin-1.0.0/mkdocs_dbml_plugin/_routing.pyx

@@ -0,0 +1,136 @@
+# cython: boundscheck=False, wraparound=False, cdivision=True
+from libc.math cimport fabs
+from libc.stdlib cimport malloc, free
+
+cdef struct Rect:
+    double x, y, w, h
+
+
+cdef int _overlaps_v(double vx, double y_lo, double y_hi,
+                     Rect *rects, int n, int skip1, int skip2) noexcept nogil:
+    cdef int i
+    cdef Rect r
+    cdef double pad = 5.0
+    for i in range(n):
+        if i == skip1 or i == skip2:
+            continue
+        r = rects[i]
+        if r.x - pad <= vx <= r.x + r.w + pad:
+            if not (y_hi < r.y - pad or y_lo > r.y + r.h + pad):
+                return i
+    return -1
+
+
+cdef double _path_cost(list waypoints):
+    cdef double cost = 0.0
+    cdef int i
+    cdef double x1, y1, x2, y2
+    for i in range(len(waypoints) - 1):
+        x1, y1 = waypoints[i]
+        x2, y2 = waypoints[i + 1]
+        cost += fabs(x2 - x1) + fabs(y2 - y1)
+    return cost
+
+
+cdef list _route_one(double sx, double sy, double ex, double ey,
+                     int skip1, int skip2, Rect *rects, int n, double gap):
+    cdef double mid_x = (sx + ex) / 2.0
+    cdef double y_lo = sy if sy < ey else ey
+    cdef double y_hi = sy if sy > ey else ey
+    cdef int blocker, dummy
+    cdef double left_x, right_x, jog_y, safe_x, stub
+    cdef bint left_ok, right_ok
+
+    blocker = _overlaps_v(mid_x, y_lo, y_hi, rects, n, skip1, skip2)
+    if blocker < 0:
+        return [(sx, sy), (mid_x, sy), (mid_x, ey), (ex, ey)]
+
+    left_x = rects[blocker].x - gap
+    right_x = rects[blocker].x + rects[blocker].w + gap
+
+    left_ok = _overlaps_v(left_x, y_lo, y_hi, rects, n, skip1, skip2) < 0
+    right_ok = _overlaps_v(right_x, y_lo, y_hi, rects, n, skip1, skip2) < 0
+
+    if left_ok and right_ok:
+        mid_x = left_x if fabs(left_x - sx) < fabs(right_x - sx) else right_x
+    elif left_ok:
+        mid_x = left_x
+    elif right_ok:
+        mid_x = right_x
+    else:
+        if sy < rects[blocker].y:
+            jog_y = rects[blocker].y - gap
+        else:
+            jog_y = rects[blocker].y + rects[blocker].h + gap
+        safe_x = left_x if fabs(left_x - sx) < fabs(right_x - sx) else right_x
+        stub = gap if ex < sx else -gap
+        return [
+            (sx, sy), (safe_x, sy), (safe_x, jog_y),
+            (ex + stub, jog_y), (ex + stub, ey), (ex, ey),
+        ]
+
+    return [(sx, sy), (mid_x, sy), (mid_x, ey), (ex, ey)]
+
+
+def route_connection(from_rect, to_rect, field_y_from, field_y_to,
+                     from_idx, to_idx, table_rects, gap=20.0):
+    cdef int n = len(table_rects)
+    cdef Rect *rects = <Rect *>malloc(n * sizeof(Rect))
+    if rects == NULL:
+        return [(0, 0), (0, 0)], 'right', 'left'
+
+    cdef int i
+    for i in range(n):
+        rects[i].x = table_rects[i][0]
+        rects[i].y = table_rects[i][1]
+        rects[i].w = table_rects[i][2]
+        rects[i].h = table_rects[i][3]
+
+    cdef double fx = from_rect[0], fy = from_rect[1], fw = from_rect[2], fh = from_rect[3]
+    cdef double tx = to_rect[0], ty = to_rect[1], tw = to_rect[2], th = to_rect[3]
+    cdef double sx, ex, cost, best_cost
+    cdef list wp, best_wp
+    cdef str best_sf, best_st
+
+    best_cost = 1e18
+    best_wp = []
+    best_sf = 'right'
+    best_st = 'left'
+
+    for sf in ('right', 'left'):
+        for st in ('right', 'left'):
+            sx = (fx + fw + 12.0) if sf == 'right' else (fx - 12.0)
+            ex = (tx - 12.0) if st == 'left' else (tx + tw + 12.0)
+            wp = _route_one(sx, field_y_from, ex, field_y_to,
+                            from_idx, to_idx, rects, n, gap)
+            cost = _path_cost(wp)
+
+            for j in range(1, len(wp) - 1):
+                mx, my = wp[j]
+                for k in range(n):
+                    if k == from_idx or k == to_idx:
+                        continue
+                    if rects[k].x <= mx <= rects[k].x + rects[k].w and rects[k].y <= my <= rects[k].y + rects[k].h:
+                        cost += 100000
+                        break
+
+            if cost < best_cost:
+                best_cost = cost
+                best_wp = wp
+                best_sf = sf
+                best_st = st
+
+    free(rects)
+    return best_wp, best_sf, best_st
+
+
+def build_table_rects(positions, dimensions):
+    names = sorted(positions.keys())
+    idx_map = {}
+    rects = []
+    for i, name in enumerate(names):
+        idx_map[name] = i
+        px, py = positions[name]
+        w, h = dimensions[name]
+        rects.append((px, py, w, h))
+    return names, idx_map, rects