References

The pages of this site tell you how to use Scraping KDL. The documents below are the canon. When a page here and a document below do not agree, the document below is correct.

The normative specification

Document	Content
Language v0.1	The full grammar, the semantics, and the validation rules.
Built-ins v0.1	Each built-in transform, with its signature and its behavior.
Selectors v0.1	The portable subset of CSS and the rejected constructions.
Diagnostics	Each diagnostic code, its severity, and its condition.
Grammar summary	The EBNF summary of the syntax.

Machine-readable data for a tool:

• builtins-v0.1.contract.json — the signatures of the transforms.
• builtins-v0.1.authoring.json — the data for an editor and for a completion.
• conformance-coverage.json — the coverage of the fixtures against the specification.

The Validated IR

Document	Content
IR schema	The JSON Schema of the Validated IR.
IR README	The version policy and the layout of the directory.
Example IR	A complete IR document.

The IR is the boundary between the compiler and a runtime. Use the schema when you write a tool that reads a program or that makes one.

The API declarations

• TypeScript index.d.ts — the portable entry point.
• TypeScript node.d.ts — the entry point for the file system.
• TypeScript authoring.d.ts — the data for an editor tool.
• Public API v1 — the stable surface of the two runtimes.

For the Go API, use go doc:

go doc github.com/hsblabs/scrape-kdl

The runtime documents

Document	Content
Compiler pipeline	The seven stages of the validation.
HTTP runtime	The behavior of the request and of the recovery.
Browser runtime	The contract of the adapter and the workflow.
Playwright adapter	The details of the TypeScript adapter.
go-rod adapter	The details of the Go adapter.
HTML compatibility	The parse of the HTML and the differences from a browser.
Performance	The measured behavior and the limits.

The compatibility and the security

Document	Content
Compatibility	The supported versions of Go, of Node.js, and of Bun.
Versioning	The version of the language, the version of the IR, and the version of the release.
Migrate to v1	The changes from an earlier version.
Changelog	The history of the releases.
Security model	The trust levels and the protections of the runtime.
Security policy	How to report a vulnerability.
Responsible use	The obligations of an operator.

The project

• Repository — the source, the fixtures, and the tests.
• Support — where to ask a question.
• Contributing — how to make a change.
• Code of conduct
• Decision records — the reason for each architectural decision.

The external standards

• KDL — the document language of the syntax. Scraping KDL accepts a documented subset.
• RE2 syntax — the profile of the regular expressions. A lookaround, a backreference, and a named group are not available.
• WHATWG HTML — the standard of the parse of the HTML.
• CSS Selectors Level 4 — the full language. The portable profile is a small subset of it.
• JSON Schema — the schema language of the IR document.