Skip to content
markdown-contract

Anchors make blocks addressable

read-03 · TypeScript

A line-terminal ^block-id names a block; a contract can require it, and a consumer can resolve it to the block’s typed view.

Builds on: One contract, two doors

The artifact

Section titled “The artifact”

A TypeScript program against the library API; inline comments show the resulting values and behavior.

import { contract, sections, section } from "markdown-contract";


// The document marks its rollback command with an anchor:
//
//   ## Rollback
//
//   ~~~sh
//   helm rollback api 41
//   ~~~
//   ^rollback-cmd
//
const runbook = contract({
  body: sections({ order: "none", allowUnknown: true }, [
    section("Rollback", { anchor: "rollback-cmd" }), // absent anchor = finding
  ]),
});


const doc = runbook.read(src, { path: "runbooks/api.md" });


const block = doc.byAnchor("rollback-cmd");
if (block?.kind === "code") {
  block.lang;   // "sh"
  block.value;  // the fenced command, verbatim
}

What it exercises

Section titled “What it exercises”
  • ^block-id anchors (dialect)
  • anchor requirements in a contract
  • doc.byAnchor() and kind-discriminated BlockView

Continue

Section titled “Continue”