Markdown Engine

Plain-language story

It checks the important parts of Markdown before people depend on it.

Teams often keep serious work in Markdown: release checklists, operating specs, handoff notes, requirements, and agent instructions. Those files are easy for humans to read, but most tools still treat them like loose text.

That means a document can look finished while a required section is missing, a table column was renamed, a release gate has no owner, or an evidence link no longer proves anything. The mistake is usually found later, during review, release, or handoff.

Markdown Engine lets a team write simple rules for the document: these sections must exist, these fields at the top must be present, these IDs must be unique, and these links must point to the right evidence. Conditional V2 profiles can also say when a rule applies, which document shapes are acceptable, how many IDs are required, and where traceability IDs must appear. Then it checks the file locally and returns clear pass/fail or skipped results that a person, CI job, or agent can trust.

Before

The Markdown looks fine.

A checklist reads well, but a release gate, owner field, or evidence link can silently drift out of shape.

Rule

The expected shape is written down.

A small rules file says which headings, fields, tables, IDs, text, links, alternatives, and conditional checks the document must satisfy.

After

The document proves it is ready.

The engine gives the same answer every time and points to what is wrong before the file is reviewed, merged, published, or handed to an agent.

Consumer value

Use Markdown where failure needs evidence.

Markdown Engine gives downstream tools a stable document model, deterministic validation, and diagnostics that can be reviewed, stored, diffed, and gated in CI.

Parse once, consume safely

Normalize GFM, frontmatter, source ranges, links, lists, tables, sections, and text spans into an engine-owned IR instead of binding consumers to raw parser ASTs.

Make conditional rules explicit

Express required headings, frontmatter fields, table columns, IDs, literal text, links, trace references, alternatives, and rule-level applicability with closed YAML-friendly profile data.

Fail locally before review

Run the CLI or API before a release, handoff, or agent task and get structured diagnostics, grouped rule details, and evaluated or skipped rule counts instead of late reviewer discovery.

Protect the deterministic boundary

V1 profiles keep their existing behavior. V2 profiles opt into conditional validation while regex-like keys, executable-like keys, accessors, proxies, cycles, and unsafe shapes stay inert.

Conditional V2 release

Profiles can branch on document reality.

`markdown-engine.validation@v2` adds conditional validation without changing the rich IR document contract. A profile can validate alternative shapes, skip non-applicable rules explicitly, enforce ID cardinality, and prove table-column traceability while v1 profiles remain on the established flat result shape.

when

Apply rules only when their precondition matches.

Rule-level applicability keeps one profile useful across variants without duplicating profile files or fabricating failures for absent sections.

anyOf / allOf

Model acceptable alternatives and grouped requirements.

Branch results stay nested and deterministic, so successful alternatives do not leak failed-branch diagnostics into the top-level outcome.

ID counts

Set minimum and maximum counts for ID families.

`ids.minCount` and `ids.maxCount` let release, requirement, and evidence tables prove expected cardinality instead of only uniqueness.

Coverage

Prove source IDs appear in the right target column.

`tableColumnCoverage` verifies configured source IDs in a configured target table column, not just somewhere in nearby prose.

Skipped results

Represent non-applicable checks as explicit evidence.

Non-matching `when` rules return `status: "skipped"`, `evaluation.kind: "skipped"`, and `skippedRuleCount` instead of disappearing from the result.

Compatibility

Keep v1 stable while v2 advances.

`profile.syntaxVersion` is the discriminator. Existing v1 profiles keep their flat rule results, evidence shape, and validation semantics.

New OKF v0.1 example seal

Validate an OKF-style bundle without making the core an OKF adapter.

OKF stands for Open Knowledge Format. Google Cloud introduced it in June 2026 as an open, vendor-neutral way to package curated knowledge as Markdown files with YAML frontmatter so both people and AI agents can read the same source.

What it is

A portable knowledge bundle made from ordinary Markdown.

An OKF bundle is just files: concept documents, optional `index.md` files for navigation, and `log.md` history. YAML frontmatter carries queryable metadata, while the body stays readable Markdown.

Why it matters

Agents need context that is not trapped in one tool.

OKF gives teams a common shape for business meaning, schemas, runbooks, metrics, and process knowledge so producers and consumers can exchange context without a proprietary service or custom SDK.

Where this package helps

Markdown Engine checks the bundle shape before consumers rely on it.

It does not discover or route OKF files. It validates the Markdown/profile pairs a caller supplies: required frontmatter, reserved-file exceptions, log date headings, and per-document evidence through `validateDocumentSet`.

Agentic repair

Agents can write, validate, repair, and retry.

A coding agent can draft OKF Markdown, run Markdown Engine locally, read structured diagnostics, repair the bundle, and repeat until the output is certifiably valid against the chosen OKF profiles.

Local policy

Teams can layer narrower rules on top of OKF.

OKF gives the shared interchange shape. Product teams can add stricter profiles for required fields, allowed concept types, naming conventions, evidence links, ownership metadata, or release-specific quality bars.

Validation proof

One caller-routed bundle, one deterministic result set.

The bundled OKF example checks typed concept frontmatter, root version metadata, reserved `index.md` and `log.md` profiles, and caller-routed document-set results.

Domain routing remains outside `markdown-engine`: no traversal, discovery, path classification, or release mutation.

Read the OKF contract section Read Google Cloud's OKF intro Review the BEL-1332 evidence

Where it fits

A foundation for profiled Markdown systems.

The package is intentionally narrow: parse, normalize, validate, serialize. That makes it useful as the deterministic substrate for docs platforms, release operations, requirements evidence, and future agent runtime lenses.

01

Docs and platform teams

Keep required document sections, frontmatter, links, tables, and structural IDs consistent across repositories.

02

Release operators

Turn release checklists into repeatable local gates before npm packing, publishing, or human approval.

03

Agent runtime builders

Feed coding agents normalized document contracts and deterministic evidence instead of asking them to infer process from raw Markdown.

Grounded workflows

Fixture workflows and profile patterns.

The Conditional V2 example maps to the release fixture suite. The v1 examples map to shipped reader fixtures, and the `SKILL.md` and `PLAYBOOK.md` patterns show how consumers can define their own document types with the same deterministic contract model.

Conditional V2

Validate alternatives, applicability, counts, and coverage.

A release team wants one profile to handle optional verification sections, grouped structural alternatives, exact requirement counts, and traceability coverage. Conditional V2 makes the skipped path explicit and still proves every REQ ID appears in the Traceability table's Requirement column.

`anyOf` accepts the matching Mission branch.
A non-matching `when` rule returns a skipped result.
REQ IDs hit exact count bounds and table-column coverage.

fixtures/declarative-validation/conditional-v2/repeatability-profile.yaml

syntaxVersion: markdown-engine.validation@v2
documentVersion: "1.0.0"
rules:
  - id: repeatability.flat.text
    select:
      target: section
      title: Mission
    assert:
      text:
        contains: launch

  - id: repeatability.grouped.anyof
    anyOf:
      - label: verification-section
        select:
          target: section
          title: Verification
        assert:
          exists: true
      - label: mission-ready
        select:
          target: section
          title: Mission
        assert:
          text:
            contains: Ready

  - id: repeatability.when.skipped
    when:
      select:
        target: section
        title: Verification
      assert:
        exists: true
    select:
      target: document
    assert:
      text:
        contains: DO NOT EVALUATE

  - id: repeatability.ids.count
    select:
      target: tableCell
      column: ID
    assert:
      ids:
        prefix: REQ
        minCount: 2
        maxCount: 2

  - id: repeatability.table.coverage
    select:
      target: document
    assert:
      tableColumnCoverage:
        source:
          section: Requirements
          column: ID
          prefix: REQ
        target:
          section: Traceability
          column: Requirement
        require: everySourceId

fixtures/declarative-validation/conditional-v2/repeatability.md

# Mission

Ready for launch.

| Owner | Status |
| --- | --- |
| Flight | Ready |

# Requirements

| ID | Statement |
| --- | --- |
| REQ-1 | Build safely |
| SYS-1 | Ignore non-requirement IDs |
| REQ-2 | Launch safely |

# Traceability

| Requirement | Evidence |
| --- | --- |
| REQ-1 | Unit test |
| REQ-2 | Integration test |

Quickstart

Install, validate, then opt into v2.

Start with the CLI to inspect behavior against bundled fixtures, then move the same deterministic path into your application code. Existing v1 profiles continue to run unchanged; Conditional V2 begins when a profile declares `syntaxVersion: markdown-engine.validation@v2`.

1

Install the package

Add the engine to the project that owns your Markdown workflow.

shell

npm install @jasonbelmonti/markdown-engine

2

Run a bundled profile

Validate a real release checklist fixture and inspect JSON output before authoring your own v2 profile.

shell

npm exec -- markdown-engine validate \
  --file node_modules/@jasonbelmonti/markdown-engine/fixtures/declarative-validation/examples/release-checklist/pass.md \
  --profile node_modules/@jasonbelmonti/markdown-engine/fixtures/declarative-validation/examples/release-checklist/profile.yaml

3

Use the API in your workflow

Parse, normalize to rich IR, compile the syntax-versioned profile, and validate locally.

TypeScript

import {
  normalize,
  parse,
  parseValidationProfile,
  validateWithProfile,
} from "@jasonbelmonti/markdown-engine";

const parsed = parse(markdown, { path: "release.md" });
const normalized = normalize(parsed.parsed);
const profileResult = parseValidationProfile(profileYaml);

if (!profileResult.profile) {
  throw new Error(profileResult.diagnostics[0]?.message ?? "Invalid profile");
}

const result = validateWithProfile(
  normalized.document,
  profileResult.profile,
  { includeEvidence: true },
);

console.log(result.valid, result.diagnostics);

Stable contracts

Built for downstream consumers.

Package 3.0 adds explicit Conditional V2 validation while keeping the serialized rich IR at `documentVersion: "1.0.0"` as the default output for `normalize(parsed)`. V1 profiles keep their existing result and evidence shape; v2 results expose rule `status`, `evaluation`, evaluated counts, and skipped counts. Legacy consumers can still request the retained `0.0.0` document shape explicitly.

Public API contract Declarative validation contract OKF validation seal evidence Frontmatter contract Changelog