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:

Five elements make this work:

• Frontmatter at the top, for metadata
• Headings (#, ##, ###) for structure and element addressing
• Narrative paragraphs for the specification language itself
• 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 — 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.

Renders as:

This is the most important principle of the markup. Each # becomes a discrete element in the system — independently addressable, independently versioned, independently citable, independently commentable. A requirement buried inside a long paragraph cannot be cited on its own; a requirement under its own heading can.

A heading does not need to have sub-headings under it. A standalone statement like #### Switchgear shall have silver-plated copper bus is a perfectly valid leaf element. When you are deciding between one long section and several shorter ones, lean toward more headings rather than fewer. Granularity is what makes a standard useful for project review, comment, and compliance tracking.

Do not skip levels. A ### must live under a ##, not directly under a #. The parser will flag any heading that jumps more than one level deeper than its predecessor.

toc_depth in the frontmatter caps which heading levels appear in the table of contents and is the mechanism every shipped standard uses today.

A {toc} marker at the end of a heading line is available as a per-heading override for finer control:

This is rarely needed in practice — set toc_depth in the frontmatter and let every heading at or above that depth appear.

Narrative is plain markdown — paragraphs, lists, bold, italic, inline code, blockquotes, and GFM pipe tables all work as you would expect. The only formatting rule specific to SynC is no hard line wrapping: write each paragraph 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:

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 drawings, not by the specification — quantities, dimensions, locations, schedules, breaker sizes. The markup has two ways to mark these. Both feed an auto-generated drawing coordination checklist that goes out with the project.

When a sentence contains a value the drawings will provide, mark it inline:

The description inside the marker should tell the reader exactly which drawing or schedule to consult.

When a datasheet field could be filled in either from the standard's options or determined from the drawings, add drawing_ref: true to the field definition. This adds a "per drawings" toggle to the form, so the specifier can defer to the drawing instead of selecting a value:

Both mechanisms feed the same coordination checklist, so the project team gets one consolidated list of every drawing-determined value across every standard used on the project.

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:

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.

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.

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

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

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).

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:

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.