Vithanco
Home / The best Tools for Structured Visual Thinking / Vithanco Graph Language (VGL) Guide

Vithanco Graph Language (VGL) Guide

Estimated reading time: 2 minutes.

VGL is a human-readable text format for creating and editing graphs — a declarative syntax for nodes, edges, groups and their attributes.

VGL is a small, declarative text format for describing graphs — diagrams made of nodes, edges, groups, and attributes. A VGL document is plain text that any editor can produce, any reviewer can diff, and any version-control tool can track. The Vithanco app reads VGL and renders it in a chosen notation (IBIS, Concept Map, Causal Loop Diagram, Goal Tree, Timeline, and many more), so the same text file can be read as prose by a human and as a typed graph by the tool.

Use VGL when you want the structure of a diagram in source form — for collaboration over pull requests, for embedding diagrams in documentation, for generating diagrams programmatically, or simply for editing complex graphs faster than you could by clicking. Each notation defines its own node and edge types and the rules that connect them, and VGL enforces those rules so you can't draw an invalid diagram.

If you're new to VGL, start with Concepts for the model (nodes, edges, groups, attributes) and Grammar for the formal syntax. Then jump to the Notation reference, which gives each built-in notation its own page: node types, edge types and a runnable example. If you want to define your own notation rather than use a built-in one, see User-Defined Notations.

Contents

Best practices

Choose descriptive ids (security_question, not n1) and name them consistently. Let edge types be inferred. Use groups to reflect the domain's real hierarchy, and comments to explain the relationships that are not obvious. Start minimal and add attributes only where they earn their place.