Skip to content

D2 Diagrams PoC

This page demonstrates D2 (Declarative Diagramming) integration with MkDocs.

Why D2?

Feature D2 Mermaid
Layout Engine TALA (commercial-grade) Dagre (basic)
Positioning near keyword Limited
SQL Tables Native sql_table shape Not supported
Themes 16+ built-in Limited
Icons 1000+ built-in Manual SVG

Architecture Overview

Clientscortex-apiServicesDataVS CodeClaude DesktopContext EngineIndexerQdrantPostgreSQL MCP/REST

Sequence Diagram

Usercortex-apiZitadelContext Engine Search RequestValidate TokenToken ValidQueryResultsResponse

State Machine

IdleRunningDoneFailed StartSuccessErrorResetNext

Database ERD

usersiduuidPKemailvarcharnamevarcharprojectsiduuidPKowner_iduuidFKnamevarchar owns

Configuration

In mkdocs.yml:

plugins:
  - d2:
      layout: tala      # Best layout engine
      theme: 1          # Neutral theme
      pad: 10           # Padding around diagrams

CI/CD Integration

D2 runs in GitLab CI, not locally:

build-docs:
  image: ghcr.io/terrastruct/d2:latest
  script:
    - mkdocs build