MarkSpec

A Markdown flavor for traceable industrial documentation, and a CLI toolchain that processes it.

Early development. The language specification is under active revision to match ADR-009 (core/profile boundary). Tooling is not yet functional.

Tools

markspec format          # stamp ULIDs, normalize attributes
markspec validate        # check broken refs, missing Ids
markspec compile <paths> # build traceability graph → JSON
                         # (ingests deps via SBOM tooling if configured)
markspec export          # JSON → csv, reqif, yaml
markspec insert          # scaffold entry block
markspec profile         # add / publish / manage profiles

markspec doc build       # document PDF
markspec book build      # PDF + HTML book
markspec book dev        # live preview
markspec deck build      # presentation PDF
markspec deck dev        # live preview

markspec lsp             # LSP server
markspec mcp             # MCP server

Modules

core/      ← parser, validator, compiler, reporter, formatter
render/    ← Typst WASM, entry block rendering, Mustache substitution, captions
book/      ← multi-file PDF + HTML book builder
deck/      ← Touying-based slide deck builder
cli/       ← subcommand handlers
lsp/       ← LSP server
mcp/       ← MCP server

One binary. One install. Three rendering targets (document, book, deck).

Markdown extensions

MarkSpec extends CommonMark with constructs that render as plain Markdown on GitHub and GitLab — no tooling required to read.

Entry blocks — a list item with a display ID and an indented body:

- [SRS_BRK_0001] Sensor input debouncing

  The sensor driver shall debounce raw inputs to eliminate electrical noise
  before processing.

  Id: 01HGW2Q8MNP3RSTVWXYZABCDEF\
  Satisfies: SYS_BRK_0042\
  Labels: ASIL-B

Every entry carries a single Id: attribute. A ULID value identifies an identified entry (content the project authors); a URI value (urn:, doi:, pkg:, https:, …) identifies a referenced entry (citation of an external artifact). The entry's type (requirement, test, unit, standard, dependency, …) is inferred by the active profile from the display-ID prefix (SRS_ → type: software-requirement); compliance vocabulary comes from the active profile.

In PDF output, entry blocks render as admonition-style blocks with profile-driven color-coding by type, label pills on the title line, and italic metadata with dashed-underline cross-references. See docs/examples/entry-rendering.md for a full showcase.

Table captions — emphasized paragraph above a pipe table:

_Table: Sensor thresholds_

| Sensor   | Min | Max  |
| -------- | --- | ---- |
| Pressure | 0   | 1023 |

Figure captions — emphasized paragraph below an image:

![System overview](overview.svg)

_Figure: High-level architecture of the braking system_

In-code entries — entries in doc comments, same format:

/// [SRS_BRK_0001] Sensor input debouncing
///
/// The sensor driver shall reject transient noise shorter
/// than the configured debounce window.
///
/// Id: 01HGW2Q8MNP3RSTVWXYZABCDEF \
/// Satisfies: SYS_BRK_0042 \
/// Labels: ASIL-B
#[test]
fn swt_brk_0001_debounce_filters_noise() {
    // test implementation
}

Mustache variables — {{project.name}} substitution from project.yaml, resolved at build time.

License

MIT

Part of the DriftSys ecosystem.

Post-clone setup

Run ./bootstrap after git clone or git worktree add.