Contributing
How the repository is laid out, how to build and test the Rust core and the Python and Node.js packages, and how releases work.
Bug reports, docs fixes, and new adapters are welcome on GitHub.
Layout
The repository follows LiteParse: one Rust core, thin binding crates, and one package per language.
| Path | What |
|---|---|
crates/pdf-textlayer |
The writer, the adapters, and the pdf-textlayer CLI. A plain Rust library. |
crates/pdf-textlayer-python |
PyO3 bindings, built as pdf_textlayer._native. |
crates/pdf-textlayer-napi |
napi-rs bindings, built as pdf-textlayer.<platform>.node. |
packages/python |
The PyPI package: typed API and CLI entry point. |
packages/node |
The npm package: TypeScript API (ESM + CJS) and CLI entry point. |
docs |
This site, built with Blume. |
examples |
A sample scan, its LiteParse JSON, and a script per language. |
benchmarks |
The synthetic dataset and the timing and agreement scripts. |
All behavior lives in crates/pdf-textlayer. A new option or entry point goes into the core first, then into both binding crates, then into the Python and Node.js wrappers and their type stubs, then these docs. Names stay parallel: snake_case in Rust and Python, camelCase in Node.js.
Build and test
You need a Rust toolchain (1.88+), uv for Python, and Node.js 20+.
make lint # cargo fmt --check, clippy, ruff, tsc
make test # Rust, Python, and Node.js suitescargo test --workspacecd packages/python
uv sync # builds the extension in release mode
uv run pytest # PyMuPDF builds fixtures and reads the output backcd packages/node
npm install
npm run build # napi build, then tsup (ESM + CJS)
npm testcd docs
npm install
npm run dev # http://localhost:4321uv sync rebuilds the extension when a Rust source changes. The Node.js package loads the .node file npm run build:rs writes next to its package.json.
Releases
The crate, the Python package, and the Node.js package share one version, released by release-please:
- Write commit messages in the Conventional Commits format.
feat:bumps the minor version,fix:the patch version, andfeat!:or aBREAKING CHANGE:footer the minor version while the project is below 1.0.chore:,ci:,docs:,refactor:, andtest:do not start a release. - On every push to
main,release-please.ymlopens or updates a release PR titledchore: release X.Y.Z. It bumps the version inCargo.toml,Cargo.lock,packages/python/pyproject.toml,packages/python/uv.lock,packages/node/package.json, andpackages/node/package-lock.json, and adds the release notes toCHANGELOG.md. - Merging the release PR tags
vX.Y.Z, creates the GitHub release, and starts the three release workflows on that tag. Approve each publish job in GitHub, then the staged npm versions on npmjs.com.
Each release workflow checks that its version matches the package before building anything. To rerun one, or to try one with the dry-run option, start it from the Actions tab.
| Workflow | Publishes |
|---|---|
release-crates.yml |
The crate to crates.io, and CLI binaries for Linux, macOS, and Windows on a GitHub release. |
release-python.yml |
abi3 wheels for every platform and an sdist to PyPI, with trusted publishing (no PyPI token). |
release-node.yml |
One npm package per platform holding its .node file, plus the main package, which lists them as optional dependencies. They are staged with trusted publishing (no npm token) and go live only after a maintainer approves them with 2FA on npmjs.com. |
Publishing jobs run in the GitHub environments npm, pypi, and crates-io, which need a maintainer’s approval and deploy only from main or a v* tag. Dry runs skip them. npm and PyPI use trusted publishing, so neither stores a token; scripts/setup-npm-trust.sh sets up the npm side once. crates.io reads CARGO_REGISTRY_TOKEN, a secret of the crates-io environment. release-please acts as a GitHub App, so CI runs on its PRs; the workflow reads the app’s client ID from the repository variable RELEASE_APP_CLIENT_ID and its private key from the secret RELEASE_APP_PRIVATE_KEY.
Docs
This site is built with Blume from the Markdown in docs/content. To deploy it on Vercel, import the repository, set the project’s Root Directory to docs, and keep the defaults from docs/vercel.json.