ext:code

Version: 1.0 Status: Stable Identifier: code

Overview

The code extension adds the ability to attach code snippets to diagram nodes. This enables documentation of implementation details, API signatures, or configuration directly within architecture diagrams.

Declaration

#!ext code
@arch My Architecture

Syntax

Code Section

Define code blocks in a [code] section:

[code]
  block_id:language:Title
    code content here
    more code...

Components:

• block_id: Unique identifier for the code block

• language: Programming language (for syntax highlighting)

• Title: Display title for the code block

Linking Nodes to Code

Reference code blocks from nodes using |code:block_id:

[nodes]
  api:API Gateway|code:api_handler

[code]
  api_handler:typescript:Request Handler
    async function handleRequest(req: Request) {
      const user = await auth.verify(req.token);
      return db.query(req.params);
    }

Supported Languages

Implementations SHOULD support syntax highlighting for common languages:

Language	Identifier
TypeScript	typescript, ts
JavaScript	javascript, js
Python	python, py
Go	go
Rust	rust
Java	java
SQL	sql
JSON	json
YAML	yaml
Shell	bash, sh

Complete Example

#!ext code
@arch API Service

[nodes,3]
  api:REST API|code:api_routes
  auth:Auth Service|code:auth_middleware
  db:PostgreSQL|cyl

[edges,2]
  api->auth:validate
  api->db:query

[code]
  api_routes:typescript:API Routes
    app.get('/users/:id', async (req, res) => {
      const user = await db.users.findById(req.params.id);
      res.json(user);
    });

  auth_middleware:typescript:Auth Middleware
    const authMiddleware = async (req, res, next) => {
      const token = req.headers.authorization;
      req.user = await verifyJWT(token);
      next();
    };

Graceful Degradation

Renderers that do not support ext:code:

1. MUST parse [code] sections without error

2. MUST ignore |code:... properties on nodes

3. MUST skip rendering of code block content

4. MUST render all nodes, edges, and groups normally

Example degradation:

• With ext:code: Node shows expandable code panel with syntax highlighting

• Without ext:code: Node renders normally, code content is not displayed

Implementation Notes

Code Block Display

Implementations may display code blocks as:

• Expandable panels attached to nodes

• Sidebar panels when node is selected

• Hover tooltips

• Separate code view tab

Syntax Highlighting

• Use standard syntax highlighting libraries (Prism, Highlight.js, etc.)

• Fall back to plain text for unknown languages

• Preserve whitespace and indentation

Code Block Scope

Code blocks are scoped to the diagram:

• Block IDs must be unique within a file

• Blocks cannot be referenced across files

• Nested diagrams inherit parent code blocks

Version History

• 1.0 (2026-01-14): Initial release