Authoring Guide

This guide explains how to design, implement, and publish TDL extensions.

What is a TDL Extension?

A TDL extension adds optional capabilities to the core TDL specification. Extensions follow the graceful degradation principle: any valid TDL file must parse successfully in any compliant renderer, even if extension features are not displayed.

Extension Types

1. Property Extensions

Add new node/edge/group properties.

Example: ext:icons adds |icon:name property

db:Database|icon:postgresql

2. Section Extensions

Add new section types with custom syntax.

Example: ext:code adds [code] section

[code]
  init:javascript:Setup
    const app = express();

3. Behavior Extensions (Future)

Add interactive behaviors like animations, linking, or state management.

Designing an Extension

Step 1: Define the Problem

• What capability are you adding?

• Why isn't this in core?

• Can it gracefully degrade?

Step 2: Design the Syntax

Follow these principles:

1. Minimal syntax - Token efficiency matters

2. Pipe-separated properties - |property:value

3. Consistent with core - Use existing patterns

Step 3: Define Graceful Degradation

For each feature, specify what happens when a renderer doesn't support it:

Feature	With Extension	Without Extension
|icon:aws	Shows AWS icon	Ignored, label shown
[code] section	Code panels	Section parsed but not rendered

Extension Specification Format

Create a markdown file with this structure:

# ext:your-extension - Extension Name

**Version**: 1.0
**Status**: Draft | Stable | Deprecated
**Identifier**: `your-extension`

## Overview
What does this extension do?

## Declaration
```tdl
#!ext your-extension

Syntax

Document all syntax additions:

• New properties

• New sections

• New values

Graceful Degradation

How should renderers without this extension behave?

Implementation Notes

Guidance for implementers.

Version History

• 1.0: Initial release

## Implementing an Extension

### For Parser Authors

1. **Parse without error** - Extension syntax is valid TDL
2. **Store in AST** - Unknown properties go to `Property[]`
3. **Pass to model** - Let renderers decide what to do

### For Renderer Authors

1. **Check for extension declaration**:
```typescript
import { hasExtension } from '@tdl/core';

if (hasExtension(model, 'icons')) {
  // Render icons
}

1. Handle missing gracefully:

const icon = node.icon;
if (icon && this.supportsIcons) {
  this.renderIcon(icon);
}
// Otherwise, just render the label

Adding a New Property Extension

1. Properties are already parsed by the core parser:

node:Label|yourprop:value

1. Extract in your renderer:

const yourValue = getPropertyValue(node.properties, 'yourprop');

1. No parser changes needed!

Adding a New Section Extension

For new sections, you have two options:

Option A: Use existing section parsing (recommended for simple cases)

• Add your section name to SectionName type in ast.ts

• Handle in semantic analyzer

Option B: Fork/extend parser (for complex syntax)

• Only if the section has unique syntax requirements

• Submit PR to core if broadly useful

Publishing an Extension

Official Extensions

To propose an official extension:

1. Create a spec in docs/tdl/extensions/your-ext.md

2. Implement in at least one renderer

3. Write tests demonstrating graceful degradation

4. Submit PR with:

   • Spec document

   • Reference implementation

   • Tests

   • SUMMARY.md update

Community Extensions

For unofficial extensions:

1. Use a namespaced identifier: community:your-ext

2. Publish spec in your own repo

3. Link from the extension registry (if we create one)

4. Document graceful degradation clearly

Extension Registry (Future)

We plan to create an extension registry:

{
  "icons": {
    "version": "1.0",
    "status": "official",
    "spec": "https://tdl-lang.org/extensions/icons"
  },
  "community:diagrams-as-code": {
    "version": "0.1",
    "status": "community",
    "spec": "https://github.com/user/tdl-diagrams-as-code"
  }
}

Best Practices

DO:

• Keep syntax minimal and consistent

• Document graceful degradation clearly

• Provide implementation examples

• Version your extension

• Test with multiple renderers

DON'T:

• Add syntax that breaks core parsing

• Require extensions for basic diagrams

• Create extensions that can't degrade gracefully

• Use reserved identifiers (core section names, properties)

Example: Creating a Simple Extension

Let's create ext:links to add clickable URLs:

1. Spec (docs/tdl/extensions/links.md)

# ext:links - Clickable Links Extension

**Version**: 1.0
**Status**: Draft
**Identifier**: `links`

## Overview
Adds clickable URL links to nodes.

## Syntax
```tdl
node:Label|url:https://example.com

Graceful Degradation

• With ext:links: Node is clickable, opens URL

• Without ext:links: URL property ignored, node renders normally

### 2. Usage

```tdl
#!ext links
@arch
[nodes]
  docs:Documentation|url:https://docs.example.com

3. Renderer Implementation

function renderNode(node: ResolvedNode) {
  const url = getPropertyValue(node.properties, 'url');

  if (url && this.supportsLinks) {
    return `<a href="${url}">${this.renderNodeContent(node)}</a>`;
  }
  return this.renderNodeContent(node);
}

Questions?

• Open an issue on the TDL repository

• Join the discussion on GitHub Discussions

• Check existing extensions for patterns