Standards Markup Syntax

A SynC Standard is more than a document. It is a structured object: every requirement is an addressable element, every configurable choice is a typed field, every revision is diffable element-by-element, and every cross-reference resolves to another standard the system knows about. The markup is what gives a plain text file all of that — and those properties are what let a standard be configured for a project, updated without forcing readers to re-read it, and reliably cited across many projects.

Most of the syntax is standard markdown. A few SynC-specific additions — datasheet blocks, cross-reference links, drawing references — handle the parts that ordinary markdown does not cover. You do not need to memorize all of it before you start. Read this page once, then use it as a lookup.

Every standard file follows the same skeleton:

---
title: Standard Title
category: Electrical
toc_depth: 3
description: >
  When to use: ...
  Not intended for: ...
---

# Section Heading {toc}

## This note explains the requirement and why it matters. {note}

## The equipment shall meet the rating selected below.

```datasheet
label: Configurable Requirement
type: select
options:
  - Option A
  - Option B
default: Option A
```

## Routing shall coordinate with [[sync/raceways-and-conduit]], [[drawing: as indicated on the one-line diagram]].

Five elements make this work:

• Frontmatter at the top, for metadata
• Headings (#, ##, ###) for structure and element addressing — each one marked as a section ({toc}), a requirement clause (unmarked), or a note ({note})
• Narrative — written as clause and note headings rather than loose paragraphs, so every statement is individually addressable
• Datasheet blocks for configurable fields
• Cross-references and drawing references as inline links to other standards and to the contract documents

Each section below covers one of these in detail.

Every standard file begins with a YAML frontmatter block between two --- lines:

---
title: Grounding and Bonding for Electrical Systems
category: Electrical
toc_depth: 3
description: >
  When to use: Grounding and bonding of low-voltage electrical systems...
  Not intended for: Lightning protection systems, medium-voltage substations...
---

• title — The displayed name of the standard. Sentence case, descriptive enough to read on its own outside the wiki nav.
• category — The library category (Electrical, Mechanical, Structural, etc.). Must match an existing category.
• toc_depth — How many heading levels appear in the generated table of contents. 2 shows top-level sections only; 3 includes their subsections; 4 includes one more level.
• description — A short two-line summary in When to use: / Not intended for: form. This is what a reader sees when deciding whether your standard is the right one for their project. Be specific about scope and exclusions.

Headings use standard markdown — # for level 1, ## for level 2, and so on. The system numbers headings automatically (1, 1.1, 1.1.1) based on nesting, so do not type numbers into the headings yourself.

# Scope
## General Requirements
### Soil Resistivity

Renders as:

1: Scope 1.1: General Requirements 1.1.1: Soil Resistivity

This is the most important principle of the markup. Each heading becomes one discrete element in the system — independently addressable (with a dotted address like 1.4.2), independently versioned, independently citable, independently commentable. Anything that is not a heading — a paragraph, a list, a table, a datasheet block — folds into the heading above it and is cited as part of that element.

That single fact drives the whole structure: if a requirement or a piece of rationale needs to be citable on its own, it has to be its own heading. A requirement buried inside a paragraph shares its parent's address and cannot be cited alone.

Every heading is one of three kinds, distinguished by a trailing marker:

• {toc} — Sections. Use it for the structural headings that organize the document: Scope, Referenced Standards, Submittals, Quality Assurance, Installation, Testing, Warranty, and their groupings. These are the headings a reader navigates by, and the only ones that appear in the table of contents. {toc} is about navigation only — a heading does not need it merely because it owns a list or datasheet.
• No marker — Requirement clauses. A requirement is left unmarked. It renders as a numbered clause with its address in the left gutter, so the gutter becomes a clean column of obligation numbers. The requirement sentence itself is the heading text: ### Deck shall be galvanized to ASTM A653 G90 minimum.
• {note} — Notes. Any narrative that is not an obligation — a scope statement, a definition, a "this section covers...", a rationale, a consequence — becomes a note. It renders as ordinary prose with its address trailing in parentheses, so it reads as explanation rather than a numbered demand. A note must never contain a shall/should/may requirement; if it does, that requirement belongs in its own clause.

If both markers somehow land on one heading, {toc} wins.

The consequence of "the heading is the element" is that a bare paragraph sitting under a heading has no address of its own. It carries citable meaning but cannot be cited, commented on, or revision-tracked — and under a clause it renders as an orphaned block of text. This is the one defect the convention exists to eliminate.

So every narrative sentence becomes its own heading:

• An obligation (shall / should / may) becomes a requirement clause (unmarked).
• Everything else — description, definition, rationale — becomes a {note}.

The only things that legitimately live as non-heading body are tables, datasheet blocks, and bullet lists. Each attaches to the heading directly above it and is cited as part of that element. That owning heading can be a section, a clause, or a note — for example, a clause that introduces a list owns it: ### The Contractor shall submit the following: followed by the bullet list and a checkbox datasheet, all cited as that clause.

Before — a compound clause with a paragraph floating under it, hiding two more requirements and a definition:

## Aesthetic Reveals {toc}
### Aesthetic reveals shall be formed in the insulation, fully back-wrapped and reinforced with base coat and mesh on all faces, and shall not reduce the insulation below the minimum thickness.
Reveals are decorative grooves cut into the EPS ... the sides and bottom shall be base-coated, meshed, and finished exactly like the field, never left as bare foam.

After — the definition is an addressable note, each obligation is its own clause, and nothing dangles:

## Aesthetic Reveals {toc}

### Reveals are decorative grooves routed into the EPS to articulate the facade; their sides and bottom are wall surface, not a free edge. {note}
### Aesthetic reveals shall be formed in the insulation and shall be fully back-wrapped.
### Reveals shall be reinforced with base coat and mesh on all faces of the groove.
### The sides and bottom of the reveal shall be base-coated, meshed, and finished exactly like the field, and shall never be left as bare foam.
### Reveals shall not reduce the insulation below the system's minimum thickness.

A clause should capture exactly one independent obligation — one normative verb-phrase, one subject. Split a compound sentence ("X and Y, and shall not Z") into one clause each where the parts are independently testable, and lift any requirement embedded in a paragraph out into its own clause. But keep an enumerated list that serves a single obligation together: "...identified by designation, profile, gauge, finish, and quantity" is one requirement — do not explode the field list.

When you are deciding between one long section and several shorter headings, lean toward more. Granularity is what makes a standard useful for project review, comment, and compliance tracking.

Do not skip levels. A heading may go only one level deeper than the one before it (# → ## → ###); jumping from # straight to ### is a parser error. Going shallower by any amount is fine. There is no depth cap — nest as deep as the requirement hierarchy genuinely needs, one step at a time.

The marker convention above is the current standard, but older standards predate it, so one rule reconciles the two:

• A document that uses zero {toc} markers is treated as legacy: every heading renders as a header, and toc_depth in the frontmatter caps which levels appear in the table of contents.
• As soon as a document uses one {toc} marker, it opts into the convention: every unmarked heading now renders as a clause. So a document using the convention must mark all of its real sections with {toc} — otherwise a section you left unmarked will render as a clause by mistake.

toc_depth still applies as the depth cap for the generated table of contents in both cases. A {toc} marker on a heading deeper than toc_depth keeps it a rendered section but it will not appear in the contents list.

Narrative carries the specification language itself, and it is the bulk of a good standard — roughly 60–70% of the content. Under the element model above, narrative is not written as loose paragraphs: each statement lives in its own heading — a requirement clause for an obligation, a {note} for description or rationale — so every statement is individually addressable. Within a heading's text and its body, ordinary markdown works as you would expect: lists, bold, italic, inline code, blockquotes, and GFM pipe tables.

The one formatting rule specific to SynC is no hard line wrapping: write each paragraph or heading as one continuous line in the source, and let the editor and renderer soft-wrap to whatever width the reader's window has. Hard-wrapping the source at 80 columns creates jagged text when the window is wider or narrower.

The narrative is binding specification language. SynC follows the construction industry's standard auxiliary verbs:

• shall — a mandatory requirement
• should — a strong recommendation; deviation requires justification
• may — optional, at the specifier's discretion

Write in active voice, directed at the responsible party ("the Contractor shall...", "the Engineer shall confirm..."). Keep it manufacturer-agnostic — no brand names, no model numbers, no "or approved equal."

To link to another standard in the same library, use the double-bracket wiki-link syntax:

Coordinate raceway routing with [[sync/raceways-and-conduit]] and conductor selection
with [[sync/conductors-and-cables]].

The format is [[library/slug]]. For standards in the SynC library, that means [[sync/the-slug]]. The rendered link displays the target standard's title automatically — you do not need to type the title.

It is fine to link to a standard that does not exist yet. Dangling references are how the library grows: each one is a signal to the next contributor about what is missing.

Construction specifications routinely contain values that are determined by the project, not by the standard — quantities, dimensions, locations, ratings, schedules. The markup has two ways to mark these, and one decision rule picks between them.

The decision rule: if the value could ever be answered with a concrete selection, make it a datasheet field. A field gives the project engineer both exits — pick a value, or defer it to the drawings — so any "either the drawings or a selection" item belongs in a datasheet block (covered in the next section). The inline [[drawing: ...]] tag is reserved for things that can never be a field: locations, routing, extents, arrangements, and details that only a drawing can express.

Marking deferrals this way is what lets a project roll every drawing-determined value, across every standard it uses, into one drawing coordination checklist — the list the project team works to zero before each issue date.

When a requirement clause defers a value to the drawings, mark the deferral inline, inside the clause it serves:

### Switchgear location and arrangement shall be [[drawing: per the equipment room layout drawings]].
### Mounting height shall be [[drawing: per the mounting detail on the drawings]].
### Frost depth shall be [[drawing: as indicated on the civil drawings or determined from the local building code]].

Three rules keep the tags useful:

• The tag text is a locator only. It tells the reader where to look — "as indicated on the one-line diagram", "per the mounting detail". The clause heading already states what must be defined, so never restate the requirement inside the tag. Naming a fallback source is fine ("or determined from the local building code").
• One tag per item. Never bundle several independent drawing-determined items into one tag — each deserves its own clause and its own tag, just as each independent obligation deserves its own clause.
• The tag lives inside the requirement clause it serves, so each deferral belongs to exactly one addressable element.

Every datasheet field can be deferred by the project engineer — "as indicated on the drawings" is always available as a field state, stored alongside the value rather than as one of the options. The author's job is only to mark the fields where deferral is the expected answer, using drawing_ref:

```datasheet
label: Main Bus Continuous Current
type: range
unit: A
drawing_ref: "one-line diagram"
options:
  min: 800
  max: 5000
  setpoints: [800, 1200, 1600, 2000, 2500, 3000, 4000, 5000]
default: 1600
```

• drawing_ref: true marks the field as commonly drawing-determined and gives it a prominent "per drawings" toggle.
• drawing_ref: "<locator>" (preferred) additionally names where the value will be found — "one-line diagram", "head anchor detail" — and pre-labels the deferral.
• default: deferred starts the field in the deferred state on a new project, so the engineer opts out by choosing a concrete value. It is only valid alongside drawing_ref (the parser rejects it otherwise), and only worth using when most projects will defer; otherwise default should be the real 80%-case option. The sentinel is a starting state, not a value — it is never stored as the field's default.

Two hard rules, enforced by the publish gate:

• options: lists real, procurable values only. Never add "Per drawings", "See schedule", or similar as an option — a deferral stored as if it were a chosen value is indistinguishable from real data and breaks the checklist roll-up.
• [[drawing: ...]] markup never goes inside a datasheet block — not in options, not in defaults, not in labels. Inline markup does not render inside datasheet YAML, so readers would see the literal brackets. The deferral belongs in drawing_ref, not in the values. Publishing a standard with [[drawing: inside datasheet YAML is rejected.

A datasheet block defines a configurable field — a place where the specifier picks an option, selects a value, or enters a project-specific input. Datasheet blocks are what turn a standard from a static document into a configurable specification: the same standard adapts to one project's 480 V service and another's 208 V service by selecting an option rather than rewriting the section.

A block is opened with ```datasheet, closed with ```, and contains YAML between the delimiters:

```datasheet
label: Voltage Rating
type: select
unit: V
options:
  - 208
  - 240
  - 480
  - 600
default: 480
```

Every datasheet block must immediately follow a heading. The block attaches to the heading above it; that attachment is how the system knows where the field belongs in the standard's structure.

The in-app editor includes a live Markup Language Reference with form previews for every type. The summary below is the quick written lookup.

Use only when no controlled input fits. Most fields in most standards should be one of the structured types below.

```datasheet
label: Special Field Conditions
type: text
options:
  multiline: true
```

Add multiline: true for a textarea instead of a single-line input.

Use when the specifier picks exactly one option from a small set (typically 2–5) and seeing all options at once is helpful.

```datasheet
label: Equipment Grounding Conductor Material
type: radio
options:
  - Copper
  - Aluminum or copper-clad aluminum
default: Copper
```

Use when one option is selected from a list that would crowd the page if shown all at once. Renders as a dropdown.

```datasheet
label: Enclosure Type
type: select
options:
  - Type 1
  - Type 3R
  - Type 4
  - Type 4X
  - Type 12
default: Type 1
```

Use when the specifier may select any combination from a small set.

```datasheet
label: Metallic Systems to be Bonded
type: checkbox
options:
  - Metal water piping system
  - Metal gas piping (interior)
  - Structural building steel
  - Metal HVAC duct systems
default:
  - Metal water piping system
```

Like checkbox, but rendered as a dropdown — use for longer lists (roughly 5 or more options) where displaying all of them inline would crowd the page.

Use for any numeric requirement. Specify min and max, then either step (uniform increments) or setpoints (specific allowed values).

```datasheet
label: Maximum Acceptable Ground Resistance
type: range
unit: ohms
options:
  min: 1
  max: 25
  setpoints: [1, 3, 5, 10, 25]
default: 5
```

Use setpoints for requirements that follow standard industry values (amperages, voltages, conduit sizes). Use step for genuinely continuous values where any multiple of the step is valid.

By default, the option label and the stored value are the same string. When you need them to differ — typically when storing a short code — use a YAML mapping in place of a list:

```datasheet
label: Installation Method
type: radio
options:
  Surface Mounted: surface
  Flush Mounted: flush
  Free Standing: freestanding
default: surface
```

The specifier sees "Surface Mounted"; the system stores surface.

Two editorial principles turn the syntax into datasheet fields that are actually useful. They are worth keeping in mind every time you add one.

One field, one decision. Each datasheet field should capture exactly one independent choice. If a field's options bundle two unrelated decisions ("Copper, 600 V" vs. "Aluminum, 1000 V"), split it into two fields. Bundled options multiply quickly into combinations no specifier wants, and they prevent a project from configuring the standard to their actual mix.

Defaults are the 80% case, not the safest case. The default should be what most projects would actually choose, so that a specifier who accepts every default ends up with a sensible specification. Defaulting to the most conservative option — highest rating, most stringent test, most expensive material — produces specifications no one uses as written, which defeats the purpose of a configurable standard.

Both principles flow from the same idea: a SynC Standard is meant to be used on real projects with minimal editing. Everything in the markup serves that goal.

The parser checks the standard as you save and surfaces errors inline. The most common ones to watch for:

• Datasheet block before any heading — every datasheet block must follow a heading, because that is how it gets attached to a section.
• Missing label or type — every datasheet block requires both.
• Empty options on a choice type — radio, select, checkbox, and listbox all need at least one option.
• range missing min/max or both step and setpoints — specify the bounds and exactly one stepping strategy.
• Heading level skipped — a ### must follow a ##, not jump from a #.
• Unclosed datasheet block — every ```datasheet must have a closing ```.

Save errors don't block your edit — they appear next to the section so you can fix them. Resolving them before publishing keeps the standard valid for downstream consumers.

• The in-app Markup Language Reference (in the standard editor) is the interactive playground for datasheet field types.
• Contributing to SynC Standards covers attribution, licensing, and the contribution process.
• Why SynC Standards Exists explains why an open library of structured standards is worth building in the first place.

The library grows one contribution at a time. The markup is just the keyboard for it.