Contributing

Updated Nov 1, 2026

Textlane is an open-source project developed by the Datist team. Everyone is welcome to help shape it with bug reports, ideas and questions; code changes come from team members.

Contributors

Report a bug

Open an issue on GitHub Issues. A good report includes:

the Textlane version and how you use it (Rust crate, npm or PyPI package)
the smallest input that reproduces the problem
the output you got and the output you expected

Use GitHub Discussions for anything that isn't a bug:

Ideas: features and improvements you'd like to see
Q&A: questions about using Textlane
Show and tell: projects built with Textlane

Ideas the team picks up turn into issues.

Members

The rest of this guide is for Datist team members working on Textlane.

Quick start

You'll need Node.js 24+, pnpm 11+ and rustup; for building the Python wheel, uv. Then:

git clone https://github.com/datisthq/textlane.git
cd textlane
pnpm install
pnpm start

pnpm install also fetches the Rust crates when cargo is on your PATH. pnpm start serves the docs site with livemark, with live reload. To run every check:

pnpm test

Repository layout

textlane/
├── rust/                # the cargo workspace, one directory per crate
│   ├── textlane/        #   the crates.io package `textlane`
│   │   ├── src/
│   │   │   ├── actions/  #   package/version, plugin/find (the plugin table), file/write
│   │   │   ├── models/   #   processor.rs (typed `with`), pipeline.rs (what the bindings drive)
│   │   │   ├── bindings/ #   node.rs (napi, `node` feature), python.rs (PyO3, `python` feature)
│   │   │   └── lib.rs    #   the library façade
│   │   ├── examples/    #   schema.rs: the option schemas `pnpm generate:bindings` reads
│   │   └── build.rs     #   napi setup under the `node` feature
│   ├── core/            #   textlane-core: trees, the file, the plugin contract
│   ├── md/ html/ mdx/ nl/  # one textlane-<domain> crate each
│   └── docs/            #   the docs site's Markdown pages, built with livemark
├── typescript/          # the npm package `textlane`: loads the native addon
│   ├── actions/         #   resolveAddon — find the platform package's addon
│   ├── generated/       #   textlane/md, /html, /mdx, /nl, from `pnpm generate:bindings`
│   ├── models/          #   the processor over the addon's pipeline, and its types
│   ├── index.ts         #   the package entry: `textlane()`
│   ├── scripts/         #   pack and publish the per-platform packages
│   └── settings.ts      #   the platform list
├── python/              # the PyPI package `textlane`: maturin PyO3 wheels
│   └── textlane/        #   the processor over the extension; md.py etc. generated
├── conformance/         # the language-neutral suite every implementation runs
├── .skills/             # shipped agent skills for people who use textlane
├── .agents/skills/      # repo skills for coding agents (see AGENTS.md)
├── .livemark/           # the docs site's livemark escapes
├── .scripts/            # repo-wide guards and the `pnpm squash` script
├── livemark.config.ts   # the docs site's config
└── vite.config.ts       # vite-plus shared config (format, lint, the guards' tests)

All behaviour lives in rust/. The npm and PyPI packages only expose the same crate, so a feature never lands in a binding.

Local commands

Run these at the repo root; each chains into the sections with pnpm -C <section>.

Command	What it does
`pnpm install`	Install dependencies
`pnpm build`	Build the release crate, the npm loader and the Python wheel
`pnpm check:types`	Type-check via `tsgo --noEmit` and `cargo check`
`pnpm check:lint`	Format check + lint (`vp fmt`, `vp lint`, `cargo fmt`, `clippy`)
`pnpm check`	`pnpm check:lint && pnpm check:types`
`pnpm format`	Auto-fix formatting (`vp fmt`, `cargo fmt`)
`pnpm generate:bindings`	Regenerate the domain modules and option types from the crate
`pnpm test:unit`	Run the repo guards, the loader's tests, `cargo test` and the conformance suite
`pnpm test`	`pnpm check && pnpm test:unit`
`pnpm start`	Serve the docs site with livemark and live reload
`pnpm build:docs`	Production build of the docs site
`pnpm read`	Serve the design notes and decisions in `.humans/` with htmlpress
`pnpm scan`	Secret and vulnerability scans (gitleaks, semgrep)

A change is ready to push when pnpm test is green.

Code conventions

Rust: edition 2024 on the pinned stable toolchain, clippy-clean with no unwrap/expect outside tests; unit tests beside the module as <module>_unit.rs, run one with cargo test <name> from rust/.
TypeScript: strict mode is on. Don't use any, as-casts, or non-null ! without permission. Full ESM imports with the .ts extension; tests beside the module as <module>.unit.ts.
Comments: docs on public items only. Skip narrative comments inside function bodies.
Docs pages: Markdown in python/docs/, typescript/docs/ and rust/docs/, one site section per language, with livemark frontmatter.
Formatting: pnpm format. 2-space indent, no semicolons, double quotes (LF, UTF-8); rustfmt at 90 columns.

Proposing a change

Open an issue first for anything bigger than a typo or a small bug. It's easier to align on direction before code.
Branch from main with a short descriptive name (e.g. fix-heading-ids, feat-gfm).
Write a focused commit history. Textlane uses Conventional Commits — the prefix drives release-please:
- fix: — bug fix → patch release
- feat: — new feature → minor release
- chore:, docs:, refactor:, test:, perf: — no release
- Only changes to what an installer gets use feat or fix; never mark a commit breaking (! or a BREAKING CHANGE: footer)
Run pnpm test before pushing.
Open a PR against main. Describe the why (link the issue), include input and output for any visible change, and call out anything reviewers should pay extra attention to.

Releases are driven by release-please: a feat or fix landing on main opens a Release PR, and merging it cuts the version, tags it, builds the native addon and wheel for every platform and publishes them to crates.io, npm and PyPI at one shared version. Maintainers don't bump versions manually.