A file format and test suite for prose documents that must survive version control.
A blockspec document is a markdown file that renders and edits correctly in today's markdown tools. It adds one convention, a marker that lets an author name a part of the document. It refuses the markdown constructs that mature parsers read differently, or that hide what a merge did.
# Runbook
<!-- #restart -->
## Restart the service
Run `systemctl restart app`, then check the logs.The marker names the heading after it, and renders as nothing. A comment or a
transclusion can point at restart and keep working when the text around it moves.
Unlike a rowspec row, a block gets no
minted id, so nothing has to be written into the prose. Identity is computed
from content where it can be, and named by an author where it must be.
DESIGN-BRIEF.md has the measurement behind that.
Draft 0. SPEC.md is the format, conformance/cases/ encodes it,
and reference/blockspec/ is the reference. reference/blockspec_alt/, written
from the spec by an author who never read it, passes the same cases. Released on
PyPI.
The experiment behind the format found that prose does have a silent wrong merge worth a format. That verdict came from a second run under an owner ruling made after the first run's result was public, so read the status page before relying on it.
From a clone, with Python 3.11 or newer and no dependencies:
git clone https://github.com/kindspec/blockspec
cd blockspec
PYTHONPATH=reference python3 -c '
import blockspec
doc = blockspec.parse("<!-- #intro -->\nHello.\n")
print(doc.names)
'parse raises Refusal, with a SPEC.md §9 code, on a document it won't
accept.
pip install blockspec
blockspec check docs/ # refuses a document the profile cannot read safelyA document is refused for what would quietly break under a merge, including a
link to a section that no longer exists and a marker that takes a name from a
heading. It exits 0 when every document reads, 1 when one is refused, and 2 when
nothing was checked or a file could not be read. --format github writes annotations. In CI:
- uses: actions/checkout@v7
- uses: kindspec/blockspec@v0.1.0
with:
paths: docsreference/blockspec/ is standard library only, and run from its source
tree (pythonpath = ["reference"]).
| function | what it does |
|---|---|
parse(text) |
reads a document, or raises Refusal with a SPEC.md §9 code; the Document has frontmatter, blocks, leaves, names and resolve(name) |
conform(text, queries) |
parse as the conformance runner calls it |
resolve(repo, queries) |
§11's anchors and transclusions, as the runner calls it (anchor.py) |
edit.replace_block(text, node, source) |
the text with block node's lines replaced by source |
edit.insert_block(text, source, before=, after=) |
the text with source inserted as a block before or after a block, or after the last |
edit.delete_block(text, node) |
the text without block node |
A block is named by its node path, [i]. Each edit function reads its
result back and raises Refusal, or its subclass edit.EditRefused for the
API's own reasons, rather than return a document whose other blocks or names
read differently. It never touches a <doc>.notes/ record.
docs/editing-api.md gives the rules, and tests/edit-cases/ pins them.
just setup # install dependencies
just check # format and lint
just test # the tests
just conform # the conformance tree against the reference
just mutants # break the reference; the suite must noticeDESIGN-BRIEF.md: what was decided and measured before the format was written.docs/adjudications/: the decisions that define draft 0.spike/: the experiment.- kindspec: the other formats.