blockspec
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.
Status
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.
Try 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.
Check documents
pip install blockspec
blockspec check docs/ # refuses a document the profile cannot read safely
A 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: docs
The reference's API
reference/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.
Develop
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 notice
More
DESIGN-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.
Metadata
Release files for blockspec 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| blockspec-0.1.0.tar.gz | 533.5 kB | With provenance | Details for blockspec-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| blockspec-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for blockspec-0.1.0-py3-none-any.whl |
Total release size: 593.0 kB
Release files / blockspec-0.1.0.tar.gz
| Download URL | blockspec-0.1.0.tar.gz |
|---|---|
| Size | 533.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
96fe6f53be3165671cd43cbf4c668d458119346e2ec6acc2848de91445f3085c
|
|
BLAKE2b-256 checksum How to use checksums |
b639edfafa34c91d092e6db488c3325d9092346b309e8fd21f3bf0c465fc6382
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.
Transparency logRelease files / blockspec-0.1.0-py3-none-any.whl
| Download URL | blockspec-0.1.0-py3-none-any.whl |
|---|---|
| Size | 59.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2660f506ee649e1b60b445d1fa80f722d57e5e59a77a4c9c7376ff8c33e10d12
|
|
BLAKE2b-256 checksum How to use checksums |
9c13ea77c3d2990949bd26a43a20351eb912ae7c6594c97e008103b055a025cc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.
Transparency logSecurity for blockspec 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for blockspec-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.