Skip to main content

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

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)

Source distribution for blockspec 0.1.0
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)

Table of built distributions (wheels) for blockspec 0.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page