A lightweight markdown extension that enables embedding formal knowledge graph structures within technical documentation. DOT-LD (DOT Linked Data) allows authors to create hybrid documents that are both human-readable and machine-processable.
DOT-LD transforms traditional technical documentation into hybrid documents containing both human-readable content and machine-readable knowledge graphs. It enables automatic generation of formal ontology-based graph representations from intuitive notation embedded directly in markdown text.
Key Principle: You write documentation in natural language, and DOT-LD syntax lets you embed formal semantic structure that both humans and machines can understand.
::config
// Define entity types with visual styling
equipment: round-rectangle, #2196F3, 120
component: ellipse, #4CAF50, 80
// Assign types to entities
ChillerSystem: type=equipment
Pump: type=component
CoolingTower: type=equipment
::
# HVAC System Documentation
The [[ChillerSystem]] is the primary cooling equipment in the facility.
It uses a [[Pump]] to circulate chilled water throughout the building
and requires a [[CoolingTower]] for heat rejection.
::rel ChillerSystem -> Pump [uses] ::
::rel ChillerSystem -> CoolingTower [requires] ::This creates:
- Human-readable documentation with clear, natural language
- Machine-readable knowledge graph with formal relationships
- Automatic visualizations from embedded structural data
DOT-LD consists of three core syntax elements:
Define your ontology and entity types:
::config
// Type definitions: shape, color, size
equipment: round-rectangle, #2196F3, 120
component: ellipse, #4CAF50, 80
// Entity type assignments
ChillerSystem: type=equipment
Pump: type=component
::Reference entities in natural language:
The [[ChillerSystem]] connects to the [[CoolingTower]]...Define semantic relationships:
::rel ChillerSystem -> CoolingTower [requires] ::
::rel ChillerSystem -> Pump [uses] ::- ✅ Human-Readable - Natural language first, structure embedded
- ✅ Machine-Processable - Formal syntax enables automated processing
- ✅ Markdown Compatible - Works with standard markdown processors
- ✅ Composable - Build knowledge graphs across multiple documents
- ✅ Domain-Agnostic - Works for any technical documentation
- ✅ Progressive Enhancement - Basic markdown functionality preserved
- System Architecture - Document components and dependencies
- API Documentation - Service relationships and data flow
- Technical Specifications - Equipment and component relationships
- Process Documentation - Workflows and procedures
- Knowledge Management - Cross-document semantic linking
- Syntax Specification - Complete formal reference
- Configuration Blocks - Ontology definition guide
- Entity References - Entity notation reference
- Relationships - Relationship syntax guide
Explore practical examples in the examples/ directory:
- Basic Example - Simplest DOT-LD document
- HVAC System - Equipment documentation
- System Architecture - Software components
- API Documentation - Service dependencies
- Process Workflow - Business processes
- Cross-Document Composition - Multi-document graphs
- Write your documentation in standard markdown
- Add a config block to define your entity types
- Reference entities using
[[EntityName]]notation - Define relationships using
::rel Source -> Target [label] :: - Process with DOT-LD tools to generate knowledge graphs
See the Basic Example for a complete walkthrough.
Traditional technical documentation faces a fundamental challenge:
- Human-readable docs lack formal structure → Hard to automate
- Machine-readable formats (XML, JSON-LD, RDF) → Hard for humans to author
DOT-LD bridges this gap by embedding formal semantic structures within natural language markdown that subject matter experts already know how to write.
| Approach | DOT-LD Advantage |
|---|---|
| Markdown Extensions (task lists, tables) | Formal ontology-based graph notation |
| Graph Languages (GraphML, DOT, Cytoscape) | Human-readable, embedded in natural text |
| Documentation Tools (Notion, Confluence) | Composable cross-document knowledge graphs |
| RDF/OWL Authoring (Protégé) | Lightweight syntax accessible to non-experts |
DOT-LD will be presented at the Knowledge Graph Conference 2026 in New York City.
- Adam Rendek - Data Center Design Optimization Manager, AWS Data Centers
- Ora Lassila - Principal Applied Scientist, AWS
- Adesoji Adeshina - Senior Applied Scientist, AWS
This project is licensed under the MIT-0 License - see the LICENSE file for details.
We welcome contributions! Please see CONTRIBUTING.md for details on how to contribute and our code of conduct.
- Open an issue on GitHub
- Reference the FAQ for common questions
- Review the Syntax Specification for technical details