Syntax & Component Reference
Reference specification for CircuitMarkdown DSL grammar, component formats, wire routing, and directives.
1. Grid & Coordinates
CircuitMarkdown uses an integer coordinate grid.
- Grid Scale: 1 grid unit equals 40 pixels.
- Coordinates: Specify integer values in parentheses, such as
(2,3)or(-1,4). - Validation: Decimal numbers cause a syntax error.
2. Comments
Comments start and end with double percent signs (%%). The parser ignores all comment text.
- Single-line:
%% This is a single-line comment %% - Inline:
R R1 "R1" "10k" (2,3) %% Trailing comment %% - Multi-line block:mdx
%% Comment line 1 Comment line 2 %%
3. Component Declaration Syntax
Every component definition uses this format:
TYPE id "designator" "value" (X,Y) [options]Required Fields
TYPE: Component mnemonic code (such asR,C,VCC,BAT_MULTI). Refer to the Component Reference for the full 50-symbol list.id: Unique identifier matching^[A-Za-z_][A-Za-z0-9_]*$."designator": Label string in double quotes (such as"R1")."value": Value string in double quotes (such as"10k","5V").(X,Y): Integer grid coordinates in parentheses.
Optional Parameters
| Parameter | Type / Values | Default | Description |
|---|---|---|---|
orient |
0, 90, 180, 270 |
0 |
Clockwise rotation angle in degrees. |
size |
Positive number | 1 |
Scale multiplier for component symbol geometry. |
refpos |
(X,Y) |
Auto | Pixel offset for designator label position. |
valpos |
(X,Y) |
Auto | Pixel offset for value label position. |
refsize |
Positive number | 16 |
Font size in pixels for designator label. |
valsize |
Positive number | 12 |
Font size in pixels for value label. |
refalign |
left, center, right |
Auto | Text alignment anchor for designator label. |
valalign |
left, center, right |
Auto | Text alignment anchor for value label. |
showref |
true, false |
true |
Visibility switch for designator label. |
showval |
true, false |
true |
Visibility switch for value label. |
4. Wire Connections
Wires connect component pins, grid coordinates, and intermediate routing waypoints. Declare wires with the W keyword:
W endpoint1 [waypoint...] endpoint2Endpoint Formats
- Pin Identifier: Use
ComponentID.PinName(such asBAT_MULTI1.+,R1.1, orQ1.B). - Grid Coordinate: Use
(X,Y)(such as(1,3)).
Intermediate Waypoints
Insert one or more grid coordinates between endpoints to guide a wire path:
Routing Behaviors
- Manhattan Routing: Wires route only along horizontal and vertical orthogonal segments.
- Junction Dots: When three or more wire paths meet at a coordinate, the renderer draws a filled junction circle.
- Hop Arcs: When two unconnected wires cross perpendicularly, the renderer draws a semicircular bridge over the intersection.
- Detour Routing: The auto-router guides wire paths around component bodies.
5. Directives & Annotations
CircuitMarkdown includes directives for standalone text annotations and drawing sheets.
TEXT Directive (Annotations)
Place standalone text labels anywhere on the schematic grid:
TEXT id "Content" (X,Y) [size=<px>] [align=left|center|right] [rot=<degrees>]| Parameter | Type / Values | Default | Description |
|---|---|---|---|
size |
Positive number | 12 |
Font size in pixels. |
align |
left, center, right |
center |
Horizontal text alignment. |
rot |
Number (0 to 360) | 0 |
Rotation angle in degrees. |
SHEET Directive (Drawing Border & Title Block)
Enclose the schematic inside a standard engineering drawing border with coordinate grid markers:
SHEET <size> [portrait|landscape]- Supported Sizes:
A4,A3,A2,A1,A0,LETTER,LEGAL,TABLOID. - Default Orientation:
landscape.
6. Circuit Examples
The examples below demonstrate valid syntax, directives, and routed circuits.